Entities

An entity represents a Mexican taxpayer registered in your organization. The API uses the entity's RFC and CIEC password to authenticate against the SAT and download CFDI documents.

Create and validate

sequenceDiagram
    autonumber
    participant App as Your app
    participant API as Meefi API
    participant SAT as SAT portal

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

    Note over API,SAT: Async credential check
    API->>+SAT: Validate CIEC for RFC
    alt CIEC valid
        SAT-->>API: Login accepted
        API->>API: credential_status → valid
        API->>App: webhook entity.update
    else CIEC invalid
        SAT-->>-API: Login rejected
        API->>API: credential_status → invalid
        API->>App: webhook entity.update
    end

    App->>+API: GET /v1/entities/{id}
    API-->>-App: 200 OK
{ credential_status: valid }

Entity object

CIEC passwords are stored encrypted and are never returned in API responses.

Create an entity

POST /v1/entities

{
  "tax_id": "XAXX010101000",
  "name": "Acme SA de CV",
  "ciec_password": "12345678"
}

Rules:

• tax_id must be unique within your organization
• ciec_password must be exactly 8 characters (SAT CIEC format)

On create, credential validation runs asynchronously. Poll GET /v1/entities/{id} until credential_status stabilizes.

Update an entity

PATCH /v1/entities/{id}

{
  "name": "Acme Updated",
  "ciec_password": "87654321"
}

When ciec_password changes:

1. credential_status resets to pending
2. Credential validation runs again

stateDiagram-v2
    [*] --> pending: POST /entities
or PATCH ciec_password
    pending --> valid: SAT accepts CIEC
    pending --> invalid: SAT rejects CIEC
    invalid --> pending: PATCH ciec_password
    valid --> pending: PATCH ciec_password

List and retrieve

• GET /v1/entities — all entities in the organization
• GET /v1/entities/{id} — single entity

Delete

DELETE /v1/entities/{id} returns 204 No Content and cascades related data.

Credential lifecycle

Do not start extractions while credential_status is pending or invalid. Extractions may fail or hang if credentials are wrong.

Webhook events

When credential status changes, an entity.update event is emitted (see Webhooks).