Getting started

Minimum integration path: authenticate, register an entity, run an extraction, and read invoices.

Integration overview

sequenceDiagram
    autonumber
    participant App as Your application
    participant API as Meefi Analytics API
    participant SAT as SAT portal

    Note over App,API: Every request uses HTTP Basic auth

    App->>+API: POST /v1/entities
    API-->>-App: 201 { id, credential_status: pending }

    loop Until credential_status = valid
        App->>+API: GET /v1/entities/{id}
        API-->>-App: 200 { credential_status }
    end

    App->>+API: POST /v1/extractions
    API-->>-App: 201 { id, status: pending }

    rect rgb(40, 50, 70)
        Note over API,SAT: Background — not blocking your request
        API->>SAT: Download & parse CFDI
        API->>API: Link payments · refresh aggregates
    end

    alt Polling
        loop Until finished or failed
            App->>+API: GET /v1/extractions/{id}
            API-->>-App: 200 { status }
        end
    else Webhooks
        API->>App: POST extraction.update
    end

    App->>+API: GET /v1/entities/{id}/invoices
    API-->>-App: 200 Paginated invoice list

Prerequisites

• Organization credentials (email + password) for HTTP Basic authentication
• A valid SAT CIEC password for the RFC you want to download
• Your API base URL (all resources live under /v1)

1. Authenticate every request

All /v1 endpoints require HTTP Basic authentication.

export API_BASE="https://api.example.com/v1"
export API_USER="[email protected]"
export API_PASS="your-password"
export AUTH_HEADER="Authorization: Basic $(printf '%s' "$API_USER:$API_PASS" | base64)"

Send the header on every call:

Authorization: Basic base64(email:password)

See Authentication for details.

2. Register an entity

An entity is a taxpayer (RFC) whose CFDI documents are downloaded from the SAT.

curl -sS -X POST "$API_BASE/entities" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_id": "XAXX010101000",
    "name": "Acme SA de CV",
    "ciec_password": "12345678"
  }'

Response fields:

Credential validation runs asynchronously. Poll GET /v1/entities/{id} until credential_status is valid before starting extractions.

3. Start an extraction

An extraction downloads CFDI for a date range, parses the XML, links related documents, and refreshes financial aggregates.

curl -sS -X POST "$API_BASE/extractions" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "YOUR_ENTITY_UUID",
    "options": {
      "period": {
        "from": "2026-01-01",
        "to": "2026-06-03"
      },
      "download_type": "issued"
    }
  }'

download_type:

Poll the extraction until processing completes:

curl -sS "$API_BASE/extractions/EXTRACTION_UUID" \
  -H "$AUTH_HEADER"

4. List invoices

Only processed invoices are returned in list endpoints.

curl -sS "$API_BASE/entities/ENTITY_UUID/invoices?payment_method=PPD&status=current" \
  -H "$AUTH_HEADER"

Common filters:

• type — CFDI type: I, E, P, N, T
• payment_method — PPD or PUE
• status — current or cancelled
• cancellation_status — cancelability: cancelable_without_acceptance, cancelable_with_acceptance, not_cancelable
• cancellation_process_status — workflow: in_progress, rejected, cancelled_without_acceptance, cancelled_with_acceptance, expired
• issued_at[after], issued_at[before] — issue date range
• certified_at[after], certified_at[before] — certification date range

See Invoices & payments for financial fields and payment behavior.

5. Download XML or PDF

curl -sS "$API_BASE/invoices/INVOICE_UUID/cfdi" \
  -H "$AUTH_HEADER" \
  -H "Accept: application/xml" \
  -o invoice.xml

Omit Accept: application/xml to receive the PDF when available.

6. Optional: webhooks

Instead of polling extraction status, register a webhook to receive extraction.update and entity.update events.

See Webhooks.

Recommended first extraction window

For accurate paid_amount, due_amount, and credited_amount on PPD invoices:

1. Run an initial historical extraction (12+ months) so original type I invoices exist before their payment complements (P) arrive.
2. Run incremental extractions (daily or weekly) to pick up new CFDI and refresh aggregates.

Payment complements reference invoice UUIDs. If the original invoice was never downloaded, the payment is stored and linked when that invoice appears in a future extraction.

Next steps

• Architecture
• Entities
• Extractions
• Invoices & payments
• SAT glossary
• Interactive API reference