Skip to main content
POST
/
api
/
timbre
/
create-invoice-full
curl -X POST https://api.usatimbre.com/api/timbre/create-invoice-full \
  -H "Authorization: Bearer tmb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_info": {
      "tax_id": "XAXX010101000",
      "cfdi_use": "G03",
      "taxpayer": "Juan Pérez García",
      "postal_code": "06600",
      "fiscal_regimen": "612"
    },
    "receipt_image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "success": true,
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "status": "processing",
      "amount": null,
      "currency": "MXN",
      "vendor": null,
      "member_rfc": "XAXX010101000",
      "created_at": "2024-01-21T10:30:00Z",
      "pdf_url": null,
      "xml_url": null
    },
    "member": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "phone_number": "+525512345678",
      "tax_id": "XAXX010101000",
      "org_id": "org_123456",
      "created_at": "2024-01-21T10:00:00Z"
    },
    "created_profile": true,
    "credits_remaining": 9
  }
}

​
Overview

Create an invoice from a receipt image in a single call. Provide complete tax info to use an existing member by RFC or automatically create a new member profile. Supports JSON (with base64 image) or multipart/form-data (with file upload).
This operation requires 1 credit. Credits are consumed from the API key owner, not the member profile.

​
Authentication

Requires a valid API key with:
  • API key owner belongs to an organization
  • api_keys_enabled feature flag enabled for the organization

​
Request Body

​
tax_info
object
required
Tax information object
​
receipt_image
string
required
Receipt image as a base64 data URL (e.g., data:image/jpeg;base64,/9j/4AAQ...). When using multipart/form-data, send as a file upload instead.
​
email
string
Contact email address
​
phone_number
string
Phone number (e.g., +525512345678, 4431041040)
​
expense_description
string
Short description of the expense (max 50 characters)

​
Behavior

  1. Validates the API key, organization, feature flag, and input fields
  2. Looks up the RFC in the caller’s organization:
    • Found — uses the existing profile
    • Not found — creates a new member profile with the provided tax data, then submits the invoice
  3. Resolves the tax regime for the invoice:
    • If fiscal_regimen is in the request, uses it (validated against member’s regimes)
    • If the member has a single regime, uses it automatically
    • If the member has multiple regimes and the provided value is not valid, returns 400
  4. Checks credits on the API key owner
  5. Submits the invoice to the invoicing provider
  6. Returns the invoice, member, and whether a new profile was created

​
Response

​
success
boolean
Whether the request was successful
​
data
object
Response data object
curl -X POST https://api.usatimbre.com/api/timbre/create-invoice-full \
  -H "Authorization: Bearer tmb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tax_info": {
      "tax_id": "XAXX010101000",
      "cfdi_use": "G03",
      "taxpayer": "Juan Pérez García",
      "postal_code": "06600",
      "fiscal_regimen": "612"
    },
    "receipt_image": "data:image/jpeg;base64,/9j/4AAQ..."
  }'

{
  "success": true,
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "status": "processing",
      "amount": null,
      "currency": "MXN",
      "vendor": null,
      "member_rfc": "XAXX010101000",
      "created_at": "2024-01-21T10:30:00Z",
      "pdf_url": null,
      "xml_url": null
    },
    "member": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "phone_number": "+525512345678",
      "tax_id": "XAXX010101000",
      "org_id": "org_123456",
      "created_at": "2024-01-21T10:00:00Z"
    },
    "created_profile": true,
    "credits_remaining": 9
  }
}

​
Error Codes

StatusCodeDescription
400MISSING_REQUIRED_FIELDSMissing tax_id, cfdi_use, fiscal_regimen, taxpayer, postal_code, or receipt_image
400INVALID_RFC_FORMATRFC doesn’t match Mexican format (12-13 chars)
400INVALID_TAX_REGIMEInvalid fiscal regime code
400INVALID_CFDI_FOR_REGIMECFDI usage code not valid for the resolved regime
400INVALID_REGIMESpecified regime not in the member’s registered regimes
400INVALID_EMAILEmail format is invalid
400INVALID_PHONE_NUMBERPhone number format is invalid
401—Missing API key
401INVALID_API_KEYAPI key not found
403NO_ORGANIZATIONAPI key owner has no organization
403FEATURE_DISABLEDapi_keys_enabled not active for the organization
403INSUFFICIENT_CREDITSNo credits remaining
404RFC_NOT_FOUNDRFC not found in organization
500LOOKUP_ERRORError looking up RFC
500AUTH_USER_CREATION_FAILEDFailed to create auth user for new profile
500PROFILE_CREATION_FAILEDFailed to create profile record
500TAX_INFO_CREATION_FAILEDFailed to create tax info record
500INTERNAL_ERRORUnexpected server error
503SERVICE_UNAVAILABLEInvoicing provider is temporarily unavailable