> ## Documentation Index
> Fetch the complete documentation index at: https://invoiceapi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable automatic SAT synchronization

> Register this profile's RFC for automatic SAT synchronization. We backfill the taxpayer's CFDI history (up to the SAT's 71-month limit) and then keep it current, mirroring both issued and received CFDIs. Authorizes with the FIEL (e.firma), not the CSD. Idempotent: re-enabling an already-registered RFC is a no-op. Expect `synced_through` to trail today by 1-3 days — the SAT does not publish a CFDI for bulk download until ~24-72h after it is issued.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/fiscal_profiles/{id}/sync
openapi: 3.1.0
info:
  title: Invoice API
  description: >-
    Mexican CFDI 4.0 invoicing API. Versioned via the Invoice-Version header;
    current: 2026-07-15. See GET /v1/versions.
  version: 0.1.0
servers:
  - url: https://api.newinvoice.dev
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: api_keys
    description: Platform API-key lifecycle (create, list, revoke)
  - name: accounts
    description: 'Connect: platform-owned connected accounts (multi-tenant)'
  - name: fiscal_profiles
    description: Emitter RFC + CSD/FIEL registration
  - name: invoices
    description: Create, stamp, cancel CFDI 4.0 invoices
  - name: validations
    description: Validate arbitrary CFDI XML
  - name: downloads
    description: SAT descarga masiva jobs
  - name: webhook_endpoints
    description: HMAC-signed event delivery
  - name: events
    description: Event log
  - name: balance
    description: Remaining stamp credits
  - name: usage
    description: Metered usage records (stamps consumed)
  - name: catalogs
    description: SAT reference catalogs (uso CFDI, payment forms/methods, tax regimes, …)
  - name: docs
    description: Served documentation (error catalog + guides)
paths:
  /v1/fiscal_profiles/{id}/sync:
    post:
      tags:
        - fiscal_profiles
      summary: Enable automatic SAT synchronization
      description: >-
        Register this profile's RFC for automatic SAT synchronization. We
        backfill the taxpayer's CFDI history (up to the SAT's 71-month limit)
        and then keep it current, mirroring both issued and received CFDIs.
        Authorizes with the FIEL (e.firma), not the CSD. Idempotent: re-enabling
        an already-registered RFC is a no-op. Expect `synced_through` to trail
        today by 1-3 days — the SAT does not publish a CFDI for bulk download
        until ~24-72h after it is issued.
      parameters:
        - schema:
            type: string
          in: path
          name: id
          required: true
          description: Fiscal profile id, e.g. fp_3k9.
        - $ref: '#/components/parameters/InvoiceVersion'
        - $ref: '#/components/parameters/InvoiceAccount'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sync_from:
                  description: >-
                    How far back to backfill, yyyy-mm-dd. Clamped to the SAT
                    limit (71 months back, floored to the 1st of that month).
                    Defaults to the maximum history available.
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                max_monthly_documents:
                  description: >-
                    Approximate CFDIs this taxpayer issues+receives per month.
                    Used to size the SAT fetch chunks — set it realistically; a
                    wrong estimate makes the backfill chunk badly.
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 1000000
                phone:
                  description: >-
                    Notification phone in international format, e.g.
                    "+5215512345678".
                  type: string
                  maxLength: 20
            example:
              sync_from: string
              max_monthly_documents: 1
              phone: string
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - fiscal_profile_sync
                  fiscal_profile_id:
                    type: string
                  rfc:
                    type: string
                  enabled:
                    type: boolean
                    description: Whether automatic SAT synchronization is turned on.
                  status:
                    type: string
                    enum:
                      - inactive
                      - pending
                      - healthy
                      - stalled
                    description: >-
                      `healthy` = the watermark is advancing. `stalled` = it has
                      stopped moving; the upstream sync died and we are
                      repairing it. `pending` = registered, first sync not yet
                      observed.
                  sync_from:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: Start of the historical backfill, yyyy-mm-dd.
                  synced_through:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      We have your CFDIs up to and including this date
                      (yyyy-mm-dd). Expect this to trail today by 1-3 days: the
                      SAT itself does not publish a CFDI for bulk download until
                      ~24-72h after it is issued.
                  lag_days:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                    description: >-
                      Days between `synced_through` and today. 1-3 is the
                      healthy steady state.
                  documents:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                    description: CFDIs mirrored for this profile so far.
                  checked_at:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - object
                  - fiscal_profile_id
                  - rfc
                  - enabled
                  - status
                  - sync_from
                  - synced_through
                  - lag_days
                  - documents
                  - checked_at
                additionalProperties: false
              example:
                object: fiscal_profile_sync
                fiscal_profile_id: fp_2P9K3sample
                rfc: XAXX010101000
                enabled: true
                status: inactive
                sync_from: string
                synced_through: string
                lag_days: -9007199254740991
                documents: 0
                checked_at: '2026-07-10T18:25:43Z'
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Missing or invalid API key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/auth_unauthorized
                title: Authentication required
                status: 401
                code: auth.unauthorized
                detail: Missing or invalid API key.
                remediation: >-
                  Send `Authorization: Bearer sk_test_...` (or sk_live_...) with
                  a valid API key.
                doc_url: /docs/errors#auth-unauthorized
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '404':
          description: Resource not found in this org + mode.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/resource_not_found
                title: Resource not found
                status: 404
                code: resource.not_found
                detail: No such id in this org + mode.
                remediation: >-
                  Verify the id and that the key mode (test/live) matches the
                  id.
                doc_url: /docs/errors#resource-not_found
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '409':
          description: Conflict (e.g. idempotency/state).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/fiscal_profile_in_use
                title: Fiscal profile is in use
                status: 409
                code: fiscal_profile.in_use
                detail: The profile is referenced by issued invoices.
                remediation: >-
                  Profiles with invoices are retained; rotate the CSD instead of
                  deleting.
                doc_url: /docs/errors#fiscal_profile-in_use
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '422':
          description: Request validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/fiscal_profile_invalid_csd
                title: Invalid CSD certificate or password
                status: 422
                code: fiscal_profile.invalid_csd
                detail: The CSD .cer/.key pair could not be opened.
                remediation: >-
                  Verify cer_base64 is the .cer, key_base64 is the .key, and the
                  password.
                doc_url: /docs/errors#fiscal_profile-invalid_csd
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
        '429':
          description: Rate limit exceeded — back off per the Retry-After header.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/rate_limit_exceeded
                title: Rate limit exceeded
                status: 429
                code: rate_limit.exceeded
                detail: >-
                  Too many requests for this key + request class (reads and
                  writes are limited separately).
                remediation: >-
                  Back off and retry after the number of seconds in the
                  Retry-After header; batch work or lower your request rate.
                doc_url: /docs/errors#rate_limit-exceeded
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://errors.invoiceapi.mx/internal_error
                title: Internal server error
                status: 500
                code: internal.error
                detail: An unexpected error occurred.
                remediation: >-
                  Retry later; contact support with the request_id if it
                  persists.
                doc_url: /docs/errors#internal-error
                request_id: req_2P9K3sample
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Invoice-Version:
              $ref: '#/components/headers/InvoiceVersionResponse'
            traceparent:
              $ref: '#/components/headers/Traceparent'
components:
  parameters:
    InvoiceVersion:
      name: Invoice-Version
      in: header
      required: false
      description: >-
        Pin a dated API release (Stripe-style). Omit to use the current version.
        An unknown value returns 400 `request.invalid_version`. Echoed back on
        every response.
      schema:
        type: string
        example: '2026-07-10'
    InvoiceAccount:
      name: Invoice-Account
      in: header
      required: false
      description: >-
        Connect: act on behalf of one of your connected accounts (its
        `acct_…`/`org_…` id). Omit to act as your own organization. Not honored
        on /v1/api_keys.
      schema:
        type: string
        example: org_2P9connectedacct
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Safely retry any POST. The first response is stored for 24h and replayed
        byte-for-byte for identical retries (the replay adds an
        `idempotent-replayed: true` header). Reusing the key with a different
        body is 409 `idempotency.key_reuse`; an in-flight duplicate is 409
        `idempotency.key_processing`. This makes retrying a 502/429 safe — no
        duplicate stamp.
      schema:
        type: string
        example: a1b2c3d4-e5f6-4789-8abc-1234567890ab
  headers:
    RequestId:
      description: >-
        Unique id for this request. Also the `request_id` in every error body —
        log it and quote it to support; idempotency keys off it too.
      schema:
        type: string
        example: req_2P9K3sample
    InvoiceVersionResponse:
      description: >-
        The dated API version resolved for this request (request header → key
        pin → current). Echoed on every response.
      schema:
        type: string
        example: '2026-07-15'
    Traceparent:
      description: >-
        W3C Trace Context. When you send a valid `traceparent`, the response
        continues the trace (same trace-id, a fresh span-id, sampled flag).
      schema:
        type: string
        example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
    RateLimitLimit:
      description: >-
        IETF draft rate-limit: the ceiling of the token bucket consulted for
        this request class (reads and writes have independent buckets).
      schema:
        type: integer
        example: 100
    RateLimitRemaining:
      description: 'IETF draft rate-limit: tokens left in the bucket after this request.'
      schema:
        type: integer
        example: 99
    RateLimitReset:
      description: 'IETF draft rate-limit: seconds until the bucket refills to its ceiling.'
      schema:
        type: integer
        example: 1
    RetryAfter:
      description: >-
        Seconds to wait before retrying (RFC 9110). Present on 429 and on
        retryable upstream failures.
      schema:
        type: integer
        example: 1
  schemas:
    Problem:
      type: object
      description: RFC 9457 problem+json error with agent-first extensions.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: Stable dotted machine code to switch on.
        detail:
          type: string
        remediation:
          type: string
          description: Actionable next step for a human or agent.
        request_id:
          type: string
        pac:
          type: object
          properties:
            provider:
              type: string
            codigo:
              type: string
            mensaje:
              type: string
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required:
        - type
        - title
        - status
        - code
        - request_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key: `Authorization: Bearer sk_test_...` or `sk_live_...`.'

````