Tatem (1.0.0)

Download OpenAPI specification:

Gustavo Rago: contacto@tatem.mx URL: https://tatem.mx Terms of Service

Tatem API

Authentication

Obtain OAuth2 Token (Resource Owner Password Credentials Grant)

This endpoint generates an access token using the resource owner password credentials grant type. If the user has 2FA enabled, a temporary token will be returned and a verification code will be sent to their WhatsApp number. The user must then submit the verification code to complete the authentication process.

Authorizations:

OAuth2

Request Body schema: application/x-www-form-urlencoded
required

One of

grant_type	string Value: "password" Must be set to `password` for initial authentication.
username	string The user's username.
password	string The user's password.
client_id	string The client ID issued by the OAuth server.
client_secret	string The client secret issued by the OAuth server.
device_id	string The trusted device ID.

Responses

Response samples

400

Content type

application/json

{"error": "invalid_request",
"error_description": "Missing client_id and/or client_secret parameters"
}

Refresh Access Token

Use a refresh token to obtain a new access token when the current one expires.

Request Body schema: application/x-www-form-urlencoded
required

grant_type	string Value: "refresh_token" Must be set to `refresh_token`.
refresh_token	string The refresh token issued during the initial authentication.
client_id	string The client ID issued by the authorization server.
client_secret	string The client secret issued by the authorization server.

Responses

Response samples

200
400

Content type

application/json

{"access_token": "string",
"token_type": "Bearer",
"expires_in": 0,
"refresh_token": "string"
}

Logout user

Invalidates the current access token and its associated refresh token

Authorizations:

OAuth2

Request Body schema: application/x-www-form-urlencoded
required

device_id

string

The trusted device ID.

Responses

Response samples

200
401

Content type

application/json

{"message": "Successfully logged out"
}

Request password reset

Requests a password reset for the user's email address

Request Body schema: application/json
required

email	string The user's email address
passwordResetPath	string The path to the password reset page. The [passwordResetCode] will be replaced with the actual password reset code.

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"passwordResetPath": "/reset-password/[passwordResetCode]"
}

Response samples

200
400
404
500

Content type

application/json

{"success": true,
"message": "Password reset request sent"
}

Reset password

Resets the user's password

Request Body schema: application/json
required

passwordResetCode	string The password reset code
password	string The new password

Responses

Request samples

Payload

Content type

application/json

{"passwordResetCode": "string",
"password": "string"
}

Response samples

200
400
404
500

Content type

application/json

{"success": true,
"message": "Password reset successfully"
}

Users

Get user information

Retrieves the authenticated user's information

Authorizations:

OAuth2

Responses

Response samples

200
401

Content type

application/json

{"id": "abcd",
"firstName": "John",
"lastName": "Sculley",
"username": "johnsculley@tatem.mx",
"email": "johnsculley@tatem.mx",
"emailVerifiedAt": "2024-12-01T17:24:59.146Z",
"whatsappNumber": "521234567890",
"whatsappNumberVerifiedAt": "2024-12-01T17:24:59.146Z",
"role": "accountant",
"createdAt": "2024-12-01T17:24:59.146Z",
"updatedAt": "2024-12-01T17:24:59.146Z",
"organizations": [{"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"isDemoMode": false
},
"role": "accountant"
}
],
"defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8",
"is2faEnabled": null,
"pendingInvitations": true
}

Create a new user

Creates a new user account with the provided information

Request Body schema: application/json
required

firstName required	string non-empty User's first name(s)
lastName required	string non-empty User's last name(s)
emailAddress required	string <email> User's email address
invitationCode	string Code for accepting an invitation
userInvitationCode	string Code for accepting an invitation to a user
password	string <password> >= 8 characters ^(?=.[a-z])(?=.[A-Z])(?=.\d)(?=.[^a-zA-Z0... Password must contain at least 8 characters, including lowercase, uppercase, number, and special character. Only required if googleIdToken isn't provided
googleIdToken	string Google ID token of the user
country	string Country of the user
region	string ISO_3166-2 region of the user
city	string City of the user

Responses

Request samples

Payload

Content type

application/json

{"firstName": "string",
"lastName": "string",
"emailAddress": "user@example.com",
"invitationCode": "string",
"userInvitationCode": "string",
"password": "pa$$word",
"googleIdToken": "string",
"country": "MX",
"region": "MX-DF",
"city": "Mexico City"
}

Response samples

200
400
404

Content type

application/json

{"success": true,
"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"firstName": "string",
"lastName": "string",
"email": "user@example.com",
"username": "user@example.com",
"role": "owner",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"pendingInvitations": true
},
"token": "string"
}

Update user information

Updates the authenticated user's information

Authorizations:

OAuth2

Request Body schema: application/json
required

firstName	string
lastName	string
emailAddress	string
whatsappNumber	string
currentPassword	string The user's current password. Required if newPassword is provided.
newPassword	string
is2faEnabled	boolean Indicates if the user has 2FA enabled.
isLastLogin	boolean If set, the users' 'lastLoginAt' field will be updated with the current date.

Responses

Request samples

Payload

Content type

application/json

{"firstName": "string",
"lastName": "string",
"emailAddress": "string",
"whatsappNumber": "string",
"currentPassword": "string",
"newPassword": "string",
"is2faEnabled": true,
"isLastLogin": true
}

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"firstName": "string",
"lastName": "string",
"email": "user@example.com",
"whatsappNumber": "string",
"role": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"verifyEmail": true,
"verifyWhatsappNumber": true
}

Delete user

Deletes the authenticated user

Authorizations:

OAuth2

Request Body schema: application/json
required

password

string

The user's password

Responses

Request samples

Payload

Content type

application/json

{"password": "password"
}

Response samples

200
400
401
403
500

Content type

application/json

{"success": true
}

Update user default organization

Updates the authenticated user's default organization

Authorizations:

OAuth2

Request Body schema: application/json
required

defaultOrganizationId

string <uuid>

Responses

Request samples

Payload

Content type

application/json

{"defaultOrganizationId": "b8c6d7f2-93a8-47a9-a281-9086316be7e8"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "User default organization updated"
}

Verify whatsapp number

Verifies the whatsapp number based on an invitation code linked to the user

Authorizations:

OAuth2

Request Body schema: application/json
required

code

required

string

The verification code sent to the user's WhatsApp number

Responses

Request samples

Payload

Content type

application/json

{"code": "123456"
}

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"message": "Whatsapp number verified"
}

Verify email address

Verifies the email address based on an invitation code linked to the user

Authorizations:

OAuth2

Request Body schema: application/json
required

code

required

string

The verification code sent to the user's email address

Responses

Request samples

Payload

Content type

application/json

{"code": "123456"
}

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"message": "Email address verified"
}

Sends the email address verification email

Sends the email address verification email to the user

Authorizations:

OAuth2

Responses

Response samples

200
401
404

Content type

application/json

{"success": true,
"message": "Email verification message sent"
}

Send WhatsApp verification code

Sends the WhatsApp verification code to the user's WhatsApp number

Authorizations:

OAuth2

Responses

Response samples

200
401
404

Content type

application/json

{"success": true,
"message": "Whatsapp verification code resent"
}

Create invitation code

Creates an invitation code for the user

Authorizations:

OAuth2

Responses

Response samples

200
401
500

Content type

application/json

{"success": true,
"invitationCode": "123456"
}

Organizations

Get organizations list

Retrieves a paginated list of organizations with optional filters

Authorizations:

OAuth2

query Parameters

provider_id required	string <uuid> ID of the provider to fetch organizations for
name	string Filter organizations by name (case-insensitive partial match)
statuses	string Example: statuses=pending,verified,not_verified Comma-separated list of organization statuses to filter by
bank_account_id	string Bank account Id assigned from the provider to filter the organizations for
include_invoice_preferences	boolean Default: false Include invoice preferences in the response
sort	string Default: "name" Enum: "name" "taxIdentifier" "status" Field to sort by
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Enum: 10 30 60 100 Number of items per page

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"status": "pending",
"invoicePreferences": {"allowedInvoiceDays": [{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
},
{"from": "string",
"to": "string"
}
],
"isPurchaseOrderMandatory": false,
"monthEndInvoiceDays": 0,
"isComplianceDocumentMandatory": false,
"isEfosClearanceMandatory": false,
"isBankingInformationMandatory": false,
"isPdfMandatory": false
},
"providers": [{"creditDays": 30,
"creditPeriod": "d",
"bankAccount": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
},
"provider": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}
]
}
],
"totalPages": 0,
"totalCount": 0
}

Create a new organization

Creates a new organization with the provided details

Request Body schema: application/json
required

commercialName	string Commercial/trading name of the organization
industry	string Industry of the organization
role	string Enum: "owner" "accountant" Role of the user creating the organization

Responses

Request samples

Payload

Content type

application/json

{"commercialName": "string",
"industry": "string",
"role": "owner"
}

Response samples

200
400
401
403

Content type

application/json

{"success": true,
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"isEntity": true,
"industry": "string",
"status": "pending",
"avatarUrl": "https://example.com/avatar.jpg"
}
}

Get organization details by ID

Retrieves detailed information about a specific organization

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the organization to retrieve

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "601",
"description": "General de Ley Personas Morales"
}
],
"cfdiUse": "G01",
"slug": "string",
"postalCode": "string",
"addressStreet": "string",
"addressNumber": "string",
"addressNumberInterior": "string",
"addressNeighborhood": "string",
"addressCity": "string",
"addressMunicipality": "string",
"addressState": "string",
"isEntity": true,
"taxIdentificationDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "TAX_IDENTIFICATION_DOCUMENT",
"filename": "string",
"url": "http://example.com"
},
"taxIdentificationDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"complianceDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "COMPLIANCE_DOCUMENT",
"filename": "string",
"url": "http://example.com"
},
"complianceDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"economicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"fielUploadedAt": "2019-08-24T14:15:22Z",
"csdUploadedAt": "2019-08-24T14:15:22Z",
"invoicesInbox": "string",
"status": "verified",
"completionStage": "none",
"facturapiValidatedAt": "2019-08-24T14:15:22Z",
"facturapiValidationErrors": "string",
"avatarUrl": "https://example.com/avatar.jpg",
"industry": "string",
"isDemoMode": true,
"contactFirstName": "Juan",
"contactLastName": "Pérez",
"contactEmailAddress": "juan.perez@example.com",
"contactPhoneNumber": "525512345678",
"contactJobTitle": "Gerente General",
"beneficiaryName": "Juan Pérez",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletionRequestedAt": "2019-08-24T14:15:22Z"
}

Update organization details

Request Body schema: application/json
required

commercialName	string Commercial/trading name of the organization
industry	string Industry of the organization
invoicesInbox	string Inbox alias for deductibles
avatarUrl	string <uri> URL of the organization's avatar image
isDemoMode	boolean Default: false
contactFirstName	string First name of the organization contact person
contactLastName	string Last name of the organization contact person
contactEmailAddress	string <email> Email address of the organization contact person
contactPhoneNumber	string Phone number of the organization contact person (international format without +)
contactJobTitle	string Job title of the organization contact person

Responses

Request samples

Payload

Content type

application/json

{"commercialName": "Turistica Dinamica San Luis",
"industry": "Turistica",
"invoicesInbox": "facturas-turistica-dinamica-san-luis",
"avatarUrl": "https://example.com/avatar.jpg",
"isDemoMode": false,
"contactFirstName": "Juan",
"contactLastName": "Pérez",
"contactEmailAddress": "juan.perez@example.com",
"contactPhoneNumber": "525512345678",
"contactJobTitle": "Gerente General"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Request delete organization

Sends a request to delete an organization. The session data will be cleared and the organization will be deleted after 30 days.

Responses

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Cancel organization deletion

Cancels the deletion request for an organization

Responses

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Get organization fiscal data by slug

Retrieves fiscal data for a specific organization by its slug

query Parameters

slug required	string Example: slug=turistica-dinamica-san-luis Slug of the organization
recaptcha_token required	string Example: recaptcha_token=1234567890 reCAPTCHA token

Responses

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"organization": {"name": "string",
"commercialName": "string",
"postalCode": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "601",
"description": "General de Ley Personas Morales"
}
],
"cfdiUse": "string",
"addressStreet": "string",
"addressNumber": "string",
"addressNumberInterior": "string",
"addressNeighborhood": "string",
"addressCity": "string",
"addressMunicipality": "string",
"addressState": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"users": [{"email": "string"
}
],
"taxIdentificationDocumentFile": {"url": "http://example.com"
}
}
}

Share organization details

Shares organization details with the user

Request Body schema: application/json
required

	Array of objects
salesReceiptFileId	string ID of the sales receipt file
paymentFormId	string ID of the payment form. Required if salesReceiptFileId is provided.
cfdiUseId	string ID of the CFDI use. Required if salesReceiptFileId is provided.

Responses

Request samples

Payload

Content type

application/json

{"invites": [{"emailAddress": "string",
"whatsappNumber": "+521234567890"
}
],
"salesReceiptFileId": "cmabyd4st0000l804a8oay86u",
"paymentFormId": "99",
"cfdiUseId": "99"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"count": 1,
"undeliverables": ["test@test.com"
]
}

Update organization bank information

Updates an organization's bank information. The user must be associated with the organization and have permission to edit organization details.

Authorizations:

OAuth2

Request Body schema: application/json
required

bankIdentifier required	string Bank identifier
beneficiaryName required	string Name of the beneficiary

Responses

Request samples

Payload

Content type

application/json

{"bankIdentifier": "123456789012345678",
"beneficiaryName": "Juan Pérez"
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Organización Ejemplo, S.A. de C.V.",
"status": "pending"
}
}

Upload organization tax identification document

Uploads a tax identification document (PDF) for an organization. The user must be associated with the organization and have permission to edit organization details.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the organization

Request Body schema: multipart/form-data
required

taxIdentificationDocumentPdf

required

string <binary>

PDF file containing the tax identification document

Responses

Response samples

Content type

application/json

{"success": true,
"message": "File uploaded successfully",
"file": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "tax_identification_document",
"filename": "string",
"url": "http://example.com"
}
}

Generate tax identification document from SAT using FIEL

Generates the tax identification document for the organization from SAT using FIEL

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to generate the tax identification document for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Upload organization compliance document

Uploads a compliance document (PDF) for an organization. The user must be associated with the organization and have permission to edit organization details.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the organization

Request Body schema: multipart/form-data
required

complianceDocumentPdf

required

string <binary>

PDF file containing the compliance document

Responses

Response samples

Content type

application/json

{"success": true,
"message": "File uploaded successfully",
"file": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "tax_identification_document",
"filename": "string",
"url": "http://example.com"
}
}

Generate compliance document from SAT using FIEL

Generates the compliance document for the organization from SAT using FIEL

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to generate the compliance document for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Get organization account balance

Retrieves the amount paid to the providers and the amount to pay within a specific date range. If no date range is provided, it returns the total amounts across all time.

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to get the account balance for

query Parameters

from	string <date> Start date for filtering invoices by payment due date (format YYYY-MM-DD)
to	string <date> End date for filtering invoices by payment due date (format YYYY-MM-DD)

Responses

Response samples

200
401
403
404
500

Content type

application/json

{"paidAmount": 0,
"dueAmount": 0,
"totalAmount": 0,
"fromDate": "2019-08-24T14:15:22Z",
"toDate": "2019-08-24T14:15:22Z"
}

Upload FIEL files and password

Uploads the FIEL certificate and key files and the password for the organization

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to upload the FIEL files and password for

Request Body schema: application/json
required

fielCertFileId	string <uuid>
fielKeyFileId	string <uuid>
fielPassword	string

Responses

Request samples

Payload

Content type

application/json

{"fielCertFileId": "123e4567-e89b-12d3-a456-426614174000",
"fielKeyFileId": "123e4567-e89b-12d3-a456-426614174000",
"fielPassword": "abcd123"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "fiel_files_uploaded",
"error": "organization_already_exists"
}

Remove FIEL files and password

Removes the FIEL certificate and key files and the password for the organization

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to remove the FIEL files and password for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "fiel_files_removed"
}

Upload CSD files and password

Uploads the CSD certificate and key files and the password for the organization

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to upload the CSD files and password for

Request Body schema: application/json
required

csdCertFileId	string <uuid>
csdKeyFileId	string <uuid>
csdPassword	string

Responses

Request samples

Payload

Content type

application/json

{"csdCertFileId": "123e4567-e89b-12d3-a456-426614174000",
"csdKeyFileId": "123e4567-e89b-12d3-a456-426614174000",
"csdPassword": "abcd123"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "csd_files_uploaded"
}

Remove CSD files and password

Removes the CSD certificate and key files and the password for the organization

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

ID of the organization to remove the CSD files and password for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "csd_files_removed"
}

Get invoice preferences for an organization

Retrieves the invoice preferences for a specific organization. The user must have permission to access invoice preferences and be associated with the organization.

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

The ID of the organization

Responses

Response samples

200
401
402
403

Content type

application/json

{"invoicePreferences": {"paymentMethods": ["string"
],
"cfdiUses": ["string"
],
"paymentForms": ["string"
],
"currencyCodes": ["string"
],
"paymentDay": 6,
"allowedInvoiceDays": [{"from": "14:15:22Z",
"to": "14:15:22Z"
}
],
"monthEndInvoiceDays": 3,
"isEfosClearanceMandatory": true,
"isComplianceDocumentMandatory": true,
"numberOfMissingPendingInvoicePaymentsAllowed": 0,
"isBankingInformationMandatory": true,
"isPurchaseOrderMandatory": true,
"isStampedAtCurrentMonthMandatory": true,
"archivePaidInvoices": true,
"archiveCompletedInvoices": true,
"archiveReceivableCompletedInvoices": true,
"archiveReceivablePaidGenericInvoices": true,
"archiveReceivablePaidGenericForeignInvoices": true,
"paymentDueAtAnchor": "createdAt",
"updateInvoicesOnCreditDaysChange": true,
"isPdfMandatory": false
}
}

Update invoice preferences for an organization

Updates the invoice preferences for a specific organization. The user must have permission to update invoice preferences and be associated with the organization.

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

The ID of the organization

Request Body schema: application/json
required

paymentMethods	Array of strings or null Payment method codes
cfdiUses	Array of strings or null CFDI use codes
paymentForms	Array of strings or null Payment form codes
currencyCodes	Array of strings or null Currency codes
paymentDay	integer or null [ 0 .. 6 ] Day of the week for payment (0-6, where 0 is Sunday)
	Array of objects or null Allowed time periods for each day of the week to submit invoices
monthEndInvoiceDays	integer or null [ 0 .. 3 ] Number of days before the end of the month to allow invoice uploads
isEfosClearanceMandatory	boolean or null Whether the clearance is mandatory for the provider to upload invoices
isComplianceDocumentMandatory	boolean or null Whether the compliance document is mandatory for the provider to upload invoices
numberOfMissingPendingInvoicePaymentsAllowed	integer or null Number of missing pending invoice payments allowed for the provider to upload invoices
isBankingInformationMandatory	boolean or null Whether the banking information is mandatory for the provider to upload invoices
isPurchaseOrderMandatory	boolean or null Whether the purchase order is mandatory for the provider to upload invoices
isStampedAtCurrentMonthMandatory	boolean or null Whether the provider can only upload invoices stamped at the current month
archivePaidInvoices	boolean or null Whether to archive paid PUE invoices
archiveCompletedInvoices	boolean or null Whether to archive completed PPD invoices
archiveReceivableCompletedInvoices	boolean or null When an invoice is completed, archive the invoice for the provider
archiveReceivablePaidGenericInvoices	boolean or null When an invoice is generic and is paid, archive the invoice for the provider
archiveReceivablePaidGenericForeignInvoices	boolean or null When an invoice is generic and foreign, and is paid, archive the invoice for the provider
paymentDueAtAnchor	string or null Enum: "createdAt" "stampedAt" "acceptedAt" The anchor date for the payment due at
updateInvoicesOnCreditDaysChange	boolean or null Whether to update credit days for all non paid invoices already sent to the organization. If set to false this change will apply to all future incoming invoices only.
isPdfMandatory	boolean or null When true, the organization requires the provider to upload an invoice PDF along with the XML when submitting an invoice. If the provider does not send a PDF, the API returns error `pdf_mandatory`.

Responses

Request samples

Payload

Content type

application/json

{"paymentMethods": ["string"
],
"cfdiUses": ["string"
],
"paymentForms": ["string"
],
"currencyCodes": ["string"
],
"paymentDay": 6,
"allowedInvoiceDays": [{"from": "14:15:22Z",
"to": "14:15:22Z"
}
],
"monthEndInvoiceDays": 3,
"isEfosClearanceMandatory": true,
"isComplianceDocumentMandatory": true,
"numberOfMissingPendingInvoicePaymentsAllowed": 0,
"isBankingInformationMandatory": true,
"isPurchaseOrderMandatory": true,
"isStampedAtCurrentMonthMandatory": true,
"archivePaidInvoices": true,
"archiveCompletedInvoices": true,
"archiveReceivableCompletedInvoices": true,
"archiveReceivablePaidGenericInvoices": true,
"archiveReceivablePaidGenericForeignInvoices": true,
"paymentDueAtAnchor": "createdAt",
"updateInvoicesOnCreditDaysChange": true,
"isPdfMandatory": true
}

Response samples

200
400
403

Content type

application/json

{"success": true
}

Get deductible preferences for an organization

Retrieves the deductible preferences for a specific organization. The user must have permission to access deductible preferences and be associated with the organization.

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

The ID of the organization

query Parameters

expand

boolean

If set to true, the expanded preferences are returned

Responses

Response samples

200
401
403

Content type

application/json

{"deductiblePreferences": {"paymentMethods": ["string"
],
"cfdiUses": ["string"
],
"paymentForms": ["string"
],
"currencyCodes": ["string"
],
"archiveNotDeductibles": true,
"archivePastDeductibles": true,
"autoApplyReasoning": true,
"autoAcceptReasoning": true,
"organization": {"name": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "601",
"description": "General de Ley Personas Morales"
}
],
"postalCode": "string",
"economicActivities": [{"economicActivity": "string",
"percentage": 0
}
]
},
"deductibleRules": {"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"isEnabled": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
}

Update deductible preferences for an organization

Updates the deductible preferences for a specific organization. The user must have permission to update deductible preferences and be associated with the organization.

Authorizations:

OAuth2

path Parameters

organizationId

required

string <uuid>

The ID of the organization

Request Body schema: application/json
required

paymentMethods	Array of strings or null Payment method codes
cfdiUses	Array of strings or null CFDI use codes
paymentForms	Array of strings or null Payment form codes
currencyCodes	Array of strings or null Currency codes
archiveNotDeductibles	boolean or null Whether to archive not deductible deductibles
archivePastDeductibles	boolean or null Whether to archive past deductibles
autoApplyReasoning	boolean or null Whether to auto apply reasoning
autoAcceptReasoning	boolean or null Whether to auto accept reasoning

Responses

Request samples

Payload

Content type

application/json

{"paymentMethods": ["string"
],
"cfdiUses": ["string"
],
"paymentForms": ["string"
],
"currencyCodes": ["string"
],
"archiveNotDeductibles": true,
"archivePastDeductibles": true,
"autoApplyReasoning": true,
"autoAcceptReasoning": true
}

Response samples

200
400
403

Content type

application/json

{"success": true
}

UserOnOrganizations

Get users on organizations

Authorizations:

OAuth2

path Parameters

id	string <uuid> ID of the organization. If not provided, the authenticated user's organizations will be returned.

query Parameters

name	string Name of the organization to filter
commercial_name	string Commercial name of the organization to filter
tax_identifier	string Tax identifier of the organization to filter
is_entity	boolean Whether the organization is an entity
sort	string Enum: "name" "commercialName" "taxIdentifier" "isEntity" Sort the organizations by a field
order	string Enum: "asc" "desc" Order the organizations by a field
page	integer Page number
limit	integer Page size

Responses

Response samples

200
400
401
403

Content type

application/json

[{"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"firstName": "string",
"lastName": "string",
"username": "string",
"lastLoginAt": "2019-08-24T14:15:22Z"
},
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"postalCode": "string",
"taxIdentifier": "string",
"isEntity": true,
"industry": "string",
"status": "verified",
"deductibleSyncStatus": "not_configured",
"deductibleSyncs": [{"tasks": [{"finishedAt": "2019-08-24T14:15:22Z"
}
]
}
]
},
"role": "collaborator",
"readAt": "2019-08-24T14:15:22Z",
"lastDeductibleReadAt": "2019-08-24T14:15:22Z",
"favoritedAt": "2019-08-24T14:15:22Z",
"disabledAt": "2019-08-24T14:15:22Z"
}
]

Update a user on an organization

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the organization

query Parameters

user_id

string <uuid>

ID of the user on the organization

Request Body schema: application/json
required

isRead	boolean
isFavorite	boolean
role	string Enum: "owner" "accountant" "collaborator" "assistant" "client" "readonly" Role of the user on the organization. Accepted only if user_id is provided.
isDisabled	boolean

Responses

Request samples

Payload

Content type

application/json

{"isRead": true,
"isFavorite": true,
"role": "owner",
"isDisabled": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Delete a user on an organization

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the organization

query Parameters

user_id

required

string <uuid>

ID of the user on the organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Providers

Update provider credit days or bank account for an organization

Updates the credit days setting or providers' bank account for a specific provider-organization relationship. The user must be associated with both the provider and organization. Only a user managing the organization side of the relationship can update credit days and period. Only a user managing the provider side of the relationship can update the bank account, except the provider is being managed by the user's organization.

Authorizations:

OAuth2

query Parameters

update_invoices

boolean

Default: false

If set to 'true', all invoices that haven't been paid will have its paymentDueAt value recalculated according to the new setting for the provider

Request Body schema: application/json
required

Any of

organizationId required	string <uuid> ID of the organization
providerId required	string <uuid> ID of the provider
creditDays	integer [ 1 .. 365 ] Number of credit days for the provider-organization relationship
creditPeriod	string Enum: "d" "m" "y" Credit period for the provider-organization relationship
bankAccountId	string or null <uuid> Id of the provider's bank account to assign to this relationship
referenceNumber	string or null Reference number for this client when doing payments to this provider
bankAccountInstructionsFileId	string or null Bank account instructions PDF file id

Responses

Request samples

Payload

Content type

application/json

{"providerOrganizations": [{"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24"
}
],
"creditDays": 30,
"creditPeriod": "d",
"bankAccountId": "5b26b598-a880-4e32-8c41-126aa0206857",
"referenceNumber": "string",
"bankAccountInstructionsFileId": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Get credit days and bank account information for a provider-organization relationship.

Get the credit days setting and provider's bank account for a specific provider-organization relationship. The user must be associated with both the provider and organization.

Authorizations:

OAuth2

query Parameters

organization_id required	any Organization Id of the provider-organization relationship
provider_id required	any Provider Id of the provider-organization relationship

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
"creditDays": 30,
"creditPeriod": "d",
"bankAccount": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true
},
"referenceNumber": "string",
"bankAccountInstructionsFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}

Catalogs

Get all tax regimes

Returns a list of all available tax regimes

Responses

Response samples

200

Content type

application/json

[{"id": "601",
"description": "General de Ley Personas Morales"
}
]

Get product keys

Returns a list of all available product keys

query Parameters

q

required

string >= 3 characters

The query to search for product keys

Responses

Response samples

200

Content type

application/json

[{"description": "string",
"key": "string"
}
]

Get unit keys

Returns a list of all available unit keys

query Parameters

q

required

string >= 3 characters

The query to search for unit keys

Responses

Response samples

200

Content type

application/json

[{"description": "string",
"key": "string"
}
]

Get CFDI usage codes

Returns a list of all valid CFDI usage codes and their descriptions

Responses

Response samples

200

Content type

application/json

[{"code": "G01",
"description": "Adquisición de mercancías",
"priority": 1
}
]

Get payment forms

Returns a list of all valid payment forms and their descriptions

Responses

Response samples

200

Content type

application/json

[{"code": "01",
"description": "Efectivo",
"priority": 1
}
]

Get payment methods

Returns a list of all valid payment methods and their descriptions

Responses

Response samples

200

Content type

application/json

[{"code": "PUE",
"description": "Pago en una sola exhibición"
}
]

Get all Mexican states

Returns a list of all Mexican states

Responses

Response samples

200

Content type

application/json

[{"code": "CDMX",
"description": "Ciudad de México"
}
]

Get all countries

Returns a list of all countries

Responses

Response samples

200

Content type

application/json

[{"code": "MX",
"description": "México"
}
]

Get all banks

Returns a list of all available banks

Responses

Response samples

200

Content type

application/json

[{"code": "012",
"description": "string"
}
]

Get all currency codes

Returns a list of all available currency codes

Responses

Response samples

200

Content type

application/json

[{"code": "USD"
}
]

Get geo data

Returns a list of all available geo data

query Parameters

postal_code

required

string

The postal code to get geo data for

Responses

Response samples

200
400
404

Content type

application/json

{"success": true,
"data": [{"neighborhood": "Colonia 1",
"city": "Ciudad de México",
"municipality": "Álvaro Obregón",
"state": "CDMX"
}
]
}

Get all taxes

Returns a list of all available taxes

Responses

Response samples

200

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string"
}
]

Get all industries

Returns a list of all available industries

Responses

Response samples

200

Content type

application/json

["Manufactura y Maquila"
]

Check if a tax identifier is in the EFOS list

Checks if a tax identifier is in the EFOS list

query Parameters

tax_identifier required	string Tax identifiers to check, comma separated
organization_id required	string <uuid>

Responses

Response samples

200
400
402

Content type

application/json

{"success": true,
"data": [{"taxIdentifier": "string",
"isInEfos": true
}
]
}

Get all job titles

Returns a list of all job titles

Responses

Response samples

200

Content type

application/json

["Dueño del negocio"
]

Files

Upload a file

Uploads a file to the system. The file type must be specified in the query parameters. Different file types have different allowed MIME types:

payment_proof: PNG, JPEG, JPG, PDF
invoice_xml: XML
invoice_pdf: PDF
tax_identification_document: PDF
purchase_order_pdf: PDF
good_standing_document: PDF
other: PDF
sales_receipt: PNG, JPEG, JPG,PDF
payment_proof_deductible: PNG, JPEG, JPG, PDF
fiel_cert_file: PEM
fiel_key_file: KEY
deductibles_upload_zip: ZIP
deductible_xml: Deductible XML
deductible_pdf: Deductible PDF
csd_cert_file: PEM
csd_key_file: KEY
expenses_upload_zip: ZIP
bank_account_instructions_pdf: PNG, JPEG, JPG, PDF

Authorizations:

OAuth2

query Parameters

type

required

string

Enum: "payment_proof" "invoice_xml" "invoice_pdf" "tax_identification_document" "purchase_order_pdf" "good_standing_document" "sales_receipt" "other" "payment_proof_deductible" "payment_receipt" "invoice_payment_xml" "invoice_payment_pdf" "zip" "xls" "fiel_cert_file" "fiel_key_file" "csd_cert_file" "csd_key_file" "deductibles_upload_zip" "deductible_xml" "deductible_pdf" "deductible_zip" "deductible_xls" "subscription_invoice_zip" "compliance_document" "expense" "expenses_zip" "expenses_xls" "expenses_upload_zip" "invoices_upload_zip" "billing_invoice_xml" "billing_invoice_pdf" "billing_invoice_zip" "bank_account_instructions_pdf" "provider_prospects_xls" "employee_contract_pdf" "payroll_xml" "payroll_report_pdf" "payroll_payment_proof"

Type of file being uploaded

Request Body schema: multipart/form-data
required

file

required

string <binary>

The file to upload

Responses

Response samples

200
400
401
500

Content type

application/json

{"success": true,
"message": "File uploaded successfully",
"file": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}

Get token for client uploads

Gets a token to upload a file to the system using client upload. The token is valid for 10 minutes.

Authorizations:

OAuth2

Responses

Response samples

200
401

Content type

application/json

{"uploadToken": "string"
}

Get file details

Retrieves details for a specific file by ID. The user must have appropriate access permissions to view the file.

Authorizations:

OAuth2

path Parameters

id

required

string

ID of the file to retrieve

Responses

Response samples

200
401
404

Content type

application/json

{"file": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}

Invitations to users

Invite users to join an organization

Authorizations:

OAuth2

Request Body schema: application/json
required

organizationIds required	Array of strings <uuid> [ items <uuid > ]
role required	string Enum: "accountant" "collaborator" "client" Role of the user in the organization
whatsappNumbers	Array of strings[ items non-empty ^[0-9]{12}$ ]
emailAddresses	Array of strings <email> [ items <email > ]
invitePath required	string non-empty Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

{"organizationIds": ["123e4567-e89b-12d3-a456-426614174000"
],
"role": "collaborator",
"whatsappNumbers": ["string"
],
"emailAddresses": ["user@example.com"
],
"invitePath": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"invitesSent": 5,
"failedInvites": ["usuario@tatem.mx"
]
}

Get invitation information sent to a user

Retrieves information associated with an invitation sent to a user.

query Parameters

user_invitation_code

required

string

The invitation code to lookup the information

Responses

Response samples

200
400
404

Content type

application/json

[{"emailAddress": "user@example.com",
"whatsappNumber": "string",
"role": "collaborator",
"createdAt": "2019-08-24T14:15:22Z",
"organizations": [{"commercialName": "string",
"taxIdentifier": "string"
}
]
}
]

Join an organization or organizations

Links the user to the organization or organizations (provided a valid invitation code)

query Parameters

user_invitation_code

required

string

Invitation code to validate the organization creation

Responses

Response samples

200
400
403
404

Content type

application/json

{"success": true
}

Invitations to organizations

Invite organizations to join a provider

query Parameters

provider_id

required

string

ID of the provider sending the invitation

Request Body schema: application/json
required

Array ([ 1 .. 100 ] items)

whatsappNumber	string non-empty ^[0-9]{12}$ Organization's WhatsApp number
emailAddress	string <email> Organization's email address
invitePath required	string non-empty Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

[{"whatsappNumber": "string",
"emailAddress": "user@example.com",
"invitePath": "string"
}
]

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"invitesSent": 5
}

Get invitation information sent to an organization

Retrieves information associated with invitations sent to an organization. If invitation_code is provided, it retrieves information associated with a specific invitation. If provider_id is provided, it retrieves all invitations sent to the organization by the provider.

query Parameters

invitation_code	string The invitation code to lookup the information
provider_id	string The ID of the provider that sent the invitations

Responses

Response samples

200
400
404

Content type

application/json

[{"emailAddress": "user@example.com",
"whatsappNumber": "string",
"invitationCode": "string",
"createdAt": "2019-08-24T14:15:22Z",
"provider": {"commercialName": "string",
"taxIdentifier": "string"
}
}
]

Delete an organization invitation

Deletes an invitation using its invitation code

query Parameters

invitation_code

required

string

The invitation code to delete

Responses

Response samples

200
400

Content type

application/json

{"success": true
}

Update an organization invitation

Updates an invitation's contact information using its invitation code

query Parameters

invitation_code

required

string

The invitation code to update

Request Body schema: application/json
required

non-empty

emailAddress	string <email> Updated email address
whatsappNumber	string^[0-9]{12}$ Updated WhatsApp number
invitePath	string non-empty Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

{"emailAddress": "user@example.com",
"whatsappNumber": "string",
"invitePath": "string"
}

Response samples

200
400
404

Content type

application/json

{"success": true
}

Resend an organization invitation

Resends an invitation to the same email and WhatsApp number using the existing invitation code

Authorizations:

OAuth2

query Parameters

invitation_code

required

string

The invitation code to resend

Request Body schema: application/json
required

non-empty

invitePath

string non-empty

Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

{"invitePath": "string"
}

Response samples

Content type

application/json

{"success": true
}

Link an organization to a provider

Links an invited organization to a provider using an invitation code

Authorizations:

OAuth2

query Parameters

invitation_code required	string The invitation code for linking the organization to the provider
organization_id required	string The ID of the organization to link to the provider

Responses

Response samples

200
400
401
404

Content type

application/json

{"success": true
}

Invitations to providers

Invite providers to join an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

ID of the organization sending the invitation

Request Body schema: application/json
required

Array ([ 1 .. 100 ] items)

whatsappNumber	string non-empty ^[0-9]{12}$ Provider's WhatsApp number
emailAddress	string <email> Provider's email address
invitePath required	string non-empty Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

[{"whatsappNumber": "string",
"emailAddress": "user@example.com",
"invitePath": "string"
}
]

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"invitesSent": 5
}

Get invitation information sent to a provider

Retrieves information associated with invitations sent to a provider. If invitation_code is provided, it retrieves information associated with a specific invitation. If organization_id is provided, it retrieves all invitations sent to the provider by the organization.

query Parameters

invitation_code	string The invitation code to lookup the information
organization_id	string The ID of the organization that sent the invitations

Responses

Response samples

200
400
404

Content type

application/json

[{"emailAddress": "user@example.com",
"whatsappNumber": "string",
"invitationCode": "string",
"createdAt": "2019-08-24T14:15:22Z",
"organization": {"commercialName": "string",
"taxIdentifier": "string"
},
"invoicePreferences": {"paymentMethods": ["string"
],
"cfdiUses": ["string"
],
"paymentForms": ["string"
],
"currencyCodes": ["string"
],
"paymentDay": 6,
"allowedInvoiceDays": [{"from": "14:15:22Z",
"to": "14:15:22Z"
}
],
"monthEndInvoiceDays": 3,
"isEfosClearanceMandatory": true,
"isComplianceDocumentMandatory": true,
"numberOfMissingPendingInvoicePaymentsAllowed": 0,
"isBankingInformationMandatory": true,
"isPurchaseOrderMandatory": true,
"isStampedAtCurrentMonthMandatory": true,
"archivePaidInvoices": true,
"archiveCompletedInvoices": true,
"archiveReceivableCompletedInvoices": true,
"archiveReceivablePaidGenericInvoices": true,
"archiveReceivablePaidGenericForeignInvoices": true,
"paymentDueAtAnchor": "createdAt"
}
}
]

Delete a provider invitation

Deletes a provider invitation by its invitation code

Authorizations:

OAuth2

query Parameters

invitation_code

required

string

The invitation code to delete

Responses

Response samples

200
400
401

Content type

application/json

{"success": true
}

Update a provider invitation

Updates an existing provider invitation's email address or WhatsApp number

Authorizations:

OAuth2

query Parameters

invitation_code

required

string

The invitation code to update

Request Body schema: application/json
required

non-empty

emailAddress	string <email> New email address for the invitation
whatsappNumber	string^[0-9]{12}$ New WhatsApp number for the invitation
invitePath	string non-empty Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

{"emailAddress": "user@example.com",
"whatsappNumber": "string",
"invitePath": "string"
}

Response samples

200
400
401
404

Content type

application/json

{"success": true
}

Create invitation code by organization slug

Authorizations:

OAuth2

query Parameters

slug

required

string

Slug of the organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"invitationCode": "123e4567-e89b-12d3-a456-426614174000"
}

Resend a provider invitation

Resends an invitation to a provider using an existing invitation code. The user must have access to the organization that sent the original invitation.

Authorizations:

OAuth2

query Parameters

invitation_code

required

string

The invitation code to resend

Request Body schema: application/json
required

non-empty

invitePath

string non-empty

Path for the invitation URL

Responses

Request samples

Payload

Content type

application/json

{"invitePath": "string"
}

Response samples

Content type

application/json

{"success": true
}

Link a provider to an organization

Links an invited provider to an organization using an invitation code

Authorizations:

OAuth2

query Parameters

invitation_code required	string The invitation code for linking the provider to the organization
provider_id required	string The ID of the provider to link to the organization

Responses

Response samples

200
400
401
404

Content type

application/json

{"success": true
}

Billing

Create a Stripe checkout session for subscription

Creates a Stripe checkout session for subscription. This endpoint is intended to be used with Stripe embedded elements. The user must have permission to access subscriptions. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:

OAuth2

query Parameters

success_path required	string Path to redirect to after successful payment
organization_id required	string Organization ID
promotion_code	string The promotion code to apply to the subscription

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"clientSecret": "string"
}

Create a Stripe checkout session for one-time payment

Creates a Stripe checkout session for one-time payment. This endpoint is intended to be used with Stripe embedded elements. The user must have permission to access balance. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:

OAuth2

query Parameters

success_path required	string Path to redirect to after successful payment
organization_id required	string Organization ID
amount required	number >= 100 Amount to pay

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"clientSecret": "string"
}

Get the status of a Stripe checkout session

Retrieves the status of a Stripe checkout session. The user must have permission to access subscriptions.

Authorizations:

OAuth2

query Parameters

session_id

required

string

Stripe checkout session ID

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"isPaymentSuccessful": true,
"status": "complete",
"amountTotal": 0,
"currency": "string",
"createdAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"paymentMethod": {"id": "string",
"type": "string",
"brand": "string",
"last4": "string"
},
"isSubscription": true
}

Create a Stripe checkout session to update payment method in Stripe

Creates a Stripe checkout session to update payment method in Stripe. The user must have permission to access billing. If the user doesn't have a Stripe customer ID, one will be created.

Authorizations:

OAuth2

query Parameters

success_path required	string Path to redirect to after successful payment
organization_id required	string Organization ID

Responses

Response samples

200
400
500

Content type

application/json

{"clientSecret": "string"
}

Get taxes for checkout session

Calculates taxes for a checkout session based on the amount and organization type. The taxes calculation depends on whether the organization is an entity or not. For entities, additional withholding taxes (ISR and VAT withholding) are applied. The user must have permission to access the organization.

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID
amount required	number >= 0.01 Amount to calculate taxes for (must be greater than 0)
percent_off	number [ 1 .. 100 ] Discount % of the amount

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"taxes": {"baseAmount": 1000,
"taxesAmount": 100,
"discountAmount": 550,
"taxes": [{"taxId": "string",
"name": "string",
"code": "string",
"isWithholding": true,
"rate": 0.1,
"amount": 100
}
]
}
}

Get billing account

Retrieve the billing account details for the authenticated user

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"billingAccount": {"id": "cl1234567890",
"name": "Tatem",
"commercialName": "Tatem",
"taxIdentifier": "XAXX010101000",
"taxRegime": "601",
"postalCode": "12345",
"cfdiUse": "G03",
"createdAt": "2024-03-20T12:00:00Z",
"updatedAt": "2024-03-20T12:00:00Z"
}
}

Create or update billing account

Create a new billing account or update an existing one for the authenticated user

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Request Body schema: application/json
required

name required	string Legal name of the company
commercialName required	string Commercial name of the company
taxIdentifier required	string RFC of the company
taxRegime required	string Tax regime code
postalCode required	string Postal code (must be 5 digits)
cfdiUse required	string CFDI use code

Responses

Request samples

Payload

Content type

application/json

{"name": "Razón Social",
"commercialName": "Nombre Comercial",
"taxIdentifier": "XAXX010101000",
"taxRegime": "601",
"postalCode": "12345",
"cfdiUse": "G03"
}

Response samples

200
400
401

Content type

application/json

{"success": true,
"billingAccount": {"id": "cl1234567890",
"name": "Tatem",
"commercialName": "Tatem",
"taxIdentifier": "XAXX010101000",
"taxRegime": "601",
"postalCode": "12345",
"cfdiUse": "G03",
"createdAt": "2024-03-20T12:00:00Z",
"updatedAt": "2024-03-20T12:00:00Z"
}
}

Get organization subscriptions

Retrieve all subscriptions for the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400
401
403

Content type

application/json

{"didHaveSubscription": true,
"subscriptions": [{"id": "sub_1234567890",
"status": "active",
"createdAt": "2023-01-01",
"updatedAt": "2023-01-01",
"cancellationScheduledAt": "2023-01-01",
"trialExpiresAt": "2023-01-01",
"currentPeriodEnd": "2023-01-01",
"billingPeriod": "monthly",
"amount": 1250,
"amountNoDiscount": 2500,
"discountPercentOff": 50,
"discountEndDate": "2026-07-01T00:00:00Z"
}
]
}

Cancels a subscription

Cancels a subscription for the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Request Body schema: application/json
required

password

required

string non-empty

User's password

Responses

Request samples

Payload

Content type

application/json

{"password": "string"
}

Response samples

200
400
401
404

Content type

application/json

{"success": true,
"message": "subscription_scheduled_for_cancellation"
}

Create a trial subscription or a paid subscription

Create a trial subscription or a paid subscription for the organization

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> The ID of the organization
payment_method_id	string <uuid> The ID of the payment method to use for the subscription. If not payment method is provided, the default payment method will be used.
promotion_code	string The promotion code to apply to the subscription

Responses

Response samples

400
401
403
404

Content type

application/json

{"error": "invalid_request_body"
}

Update a subscription promotion code

Update an existing subscription with a new promotion code

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> The ID of the organization
promotion_code required	string The promotion code to apply to the subscription

Responses

Response samples

400
401
403
404

Content type

application/json

{"error": "invalid_request_body"
}

Resume a paused subscription

Resume a paused subscription for the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

The ID of the organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Answer survey

Submit a survey answer for the organization

Authorizations:

OAuth2

Request Body schema: application/json
required

answer required	string [ 1 .. 1000 ] characters The survey answer text
organizationId required	string <uuid> The ID of the organization

Responses

Request samples

Payload

Content type

application/json

{"answer": "string",
"organizationId": "cmgy9k6u1000l1n3sx22aw62r"
}

Response samples

200
400
401
403

Content type

application/json

{"success": true
}

Get billing invoices

Retrieve all invoices for the authenticated user

Authorizations:

OAuth2

query Parameters

created_at_from	string <date-time> Filter billing invoices created after this date
created_at_to	string <date-time> Filter billing invoices created before this date
is_subscription	any
page	integer Default: 1 Page number
limit	any Number of invoices per page

Responses

Response samples

200
401
404
500

Content type

application/json

{"success": true,
"invoices": [{"id": "1234567890",
"createdAt": "2023-01-01",
"updatedAt": "2023-01-01",
"subscriptionId": "1234567890",
"paymentMethod": {"last4": "string"
},
"pdfFile": {"url": "string"
},
"status": "paid",
"total": 1000,
"currency": "MXN"
}
]
}

Download billing invoices as ZIP

Download multiple billing invoices as a ZIP file containing their PDF files

Authorizations:

OAuth2

Request Body schema: application/json
required

billingInvoiceIds

required

Array of strings [ 1 .. 100 ] items

Array of billing invoice IDs to download

Responses

Request samples

Payload

Content type

application/json

{"billingInvoiceIds": ["invoice_123",
"invoice_456",
"invoice_789"
]
}

Response samples

Content type

application/json

{"id": "file_1234567890",
"filename": "Facturas Tátem - 25 oct 25 - ABC123456789.zip",
"type": "billing_invoice_zip",
"status": "processing",
"createdAt": "2023-10-25T10:30:00Z"
}

Get payment methods

Get the payment methods for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

The ID of the organization

Responses

Response samples

200
400
401
403

Content type

application/json

[{"id": "string",
"type": "card",
"brand": "visa",
"last4": "1234",
"expirationMonth": 0,
"expirationYear": 0,
"isDefault": true,
"isExpired": true,
"organizationId": "string",
"stripePaymentMethodId": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Delete payment method

Delete a payment method for an organization

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

The ID of the payment method to delete

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Set default payment method

Set a payment method as the default for an organization

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

The ID of the payment method to set as default

Responses

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Get promotion code details

Validate a Stripe promotion code and retrieve the discount percentage

Authorizations:

OAuth2

query Parameters

promotion_code

required

string

The promotion code to validate

Responses

Response samples

200
400
401
404

Content type

application/json

{"percent_off": 20,
"duration": "forever",
"duration_in_months": 6
}

Get billing settings

Retrieves billing settings for an organization. The user must belong to the organization and have permission to view billing settings. Returns null if no billing settings exist for the organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Organization ID

Responses

Response samples

200
400
401
403

Content type

application/json

Example

BillingSettings

{"organizationId": "cl1234567890",
"autorechargeBalanceEnabled": false,
"autorechargeBalanceBelowThreshold": "string",
"autorechargeBalanceValue": "string",
"autorechargePrimaryPaymentMethodId": "string",
"autorechargeSecondaryPaymentMethodId": "string",
"autorechargePrimaryPaymentMethod": {"id": "string",
"type": "string",
"brand": "string",
"last4": "string",
"isDefault": true
},
"autorechargeSecondaryPaymentMethod": {"id": "string",
"type": "string",
"brand": "string",
"last4": "string",
"isDefault": true
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update billing settings

Creates or updates billing settings for an organization. The user must belong to the organization and have permission to update billing settings (readonly users cannot update). Payment method IDs must belong to the organization.

Authorizations:

OAuth2

Request Body schema: application/json
required

organizationId required	string <uuid> Organization ID
autorechargeBalanceEnabled	boolean Whether to enable balance autorecharge
	(number or null) or (string or null) Balance threshold below which autorecharge is triggered
	(number or null) or (string or null) Target balance to raise to when autorecharge is triggered.
autorechargePrimaryPaymentMethodId	string or null ID of the primary payment method for autorecharge
autorechargeSecondaryPaymentMethodId	string or null ID of the secondary payment method for autorecharge

Responses

Request samples

Payload

Content type

application/json

{"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"autorechargeBalanceEnabled": true,
"autorechargeBalanceBelowThreshold": 0,
"autorechargeBalanceValue": 0,
"autorechargePrimaryPaymentMethodId": "string",
"autorechargeSecondaryPaymentMethodId": "string"
}

Response samples

200
400
401
403

Content type

application/json

{"organizationId": "cl1234567890",
"autorechargeBalanceEnabled": false,
"autorechargeBalanceBelowThreshold": "string",
"autorechargeBalanceValue": "string",
"autorechargePrimaryPaymentMethodId": "string",
"autorechargeSecondaryPaymentMethodId": "string",
"autorechargePrimaryPaymentMethod": {"id": "string",
"type": "string",
"brand": "string",
"last4": "string",
"isDefault": true
},
"autorechargeSecondaryPaymentMethod": {"id": "string",
"type": "string",
"brand": "string",
"last4": "string",
"isDefault": true
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Deductibles

Get deductibles list

Retrieves a paginated list of deductibles with optional filters

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch deductibles for
uuid	string <uuid> Filter by deductible UUID
folio_number	string Example: folio_number=1234567890,1234567891 Comma separated list of folio numbers to filter by
statuses	string Example: statuses=deductible,not_deductible,not_valid Comma-separated list of deductible statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
created_at_period	string Example: created_at_period=2025-01 Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
sort	string Default: "uuid" Enum: "uuid" "grossPriceAmount" "status" "createdAt" "updatedAt" "issuerName" "issuedAt" "stampedAt" Comma-separated list of fields to sort by
order	string Default: "desc" Enum: "asc" "desc" Comma-separated list of sort orders to sort by. The number of values in this parameter must match exactly the number of values in the 'order' parameter.
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 30 Enum: 10 30 60 100 Number of items per page
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
is_entity	boolean Default: false Filter by entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"folioNumber": "1234567890",
"series": "S",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"commercialName": "string"
},
"paymentMethod": "PPD",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"status": "processing",
"createdAt": "2024-12-01T17:24:59.146Z",
"updatedAt": "2024-12-01T17:24:59.146Z",
"issuedAt": "2024-12-01T17:24:59.146Z",
"stampedAt": "2024-12-01T17:24:59.146Z",
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0,
"isCancelled": false,
"readAt": "2024-12-01T17:24:59.146Z",
"items": [{"description": "Factura por pagar",
"quantity": 1,
"unitKey": "unit",
"unitDescription": "Unidad",
"itemKey": "item",
"discount": 10
}
],
"taxes": [{"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0
}
],
"notes": "Notas de la factura",
"paymentProofFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"reasoning": {"status": "processing"
},
"isDemo": true,
"invoice": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"payments": [{"payment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "processing",
"paidAt": "2019-08-24T14:15:22Z",
"paymentProofFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"paymentReceipt": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"paymentReceiptFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}
}
}
]
}
}
],
"grossPriceAmount": 0,
"taxesAmount": [{"code": "string",
"value": 100,
"isWithholding": false
}
],
"unreadCount": 0,
"totalPages": 0,
"totalCount": 0,
"itemCount": 0,
"itemsWithChartCount": 0
}

Update deductibles

Updates a list of deductibles

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch deductibles for
uuid	string <uuid> Filter by deductible UUID
statuses	string Example: statuses=deductible,not_deductible,not_valid Comma-separated list of deductible statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
created_at_period	string Example: created_at_period=2025-01 Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
is_entity	boolean Default: false Filter by entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description

Request Body schema: application/json
required

deductibleIds	Array of strings <uuid> <= 100 items [ items <uuid > ]
archive	boolean Whether to archive (true) or unarchive (false) the deductible
status	string Enum: "deductible" "review" "semi_deductible" "not_deductible"
isRead	boolean

Responses

Request samples

Payload

Content type

application/json

{"deductibleIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"archive": false,
"status": "deductible",
"isRead": true
}

Response samples

Content type

application/json

{"success": true,
"archivedDeductibles": ["123e4567-e89b-12d3-a456-426614174000"
]
}

Create a new deductible

Creates a new deductible by uploading XML and PDF files

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization the deductible is for

Request Body schema: multipart/form-data
required

invoiceXml required	string <binary> XML file containing the CFDI invoice data
invoicePdf	string <binary> PDF version of the invoice

Responses

Response samples

Content type

application/json

{"success": true,
"deductible": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"message": "File uploaded successfully"
}

Upload deductibles as zip

Authorizations:

OAuth2

Request Body schema: application/json
required

deductiblesUploadZipId

required

string <uuid>

Responses

Request samples

Payload

Content type

application/json

{"deductiblesUploadZipId": "bcd5f9d8-7a58-4133-b91e-ea57672ab67c"
}

Response samples

Content type

application/json

{"success": true
}

Delete multiple deductibles

Deletes multiple deductibles

Authorizations:

OAuth2

Request Body schema: application/json
required

deductibleIds required	Array of strings <uuid> non-empty [ items <uuid > ]
convertToInvoice	boolean Default: false

Responses

Request samples

Payload

Content type

application/json

{"deductibleIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"convertToInvoice": false
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Get deductibles balance

Retrieves the balance of deductibles for an organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch deductibles for
uuid	string <uuid> Filter by deductible UUID
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
created_at_period	string Example: created_at_period=2025-01 Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issuer_name	string Example: issuer_name=test Filter by issuer name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
is_entity	boolean Default: false Filter by entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description

Responses

Response samples

200
400
401

Content type

application/json

{"grossPriceAmount": 0,
"taxesAmount": [{"code": "string",
"value": 100,
"isWithholding": false
}
]
}

Get top charts for deductibles

Retrieves the top charts for deductibles

query Parameters

organization_id

string <uuid>

ID of the organization to fetch deductibles for

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"code": "string",
"description": "string",
"totalAmount": 0,
"deductibleCount": 0
}
]
}

Create a new deductible batch

Creates a new deductible batch

query Parameters

organization_id

required

string <uuid>

ID of the organization to delete the deductible sync for

Request Body schema: application/json
required

fromDate	string <date> Start date of the batch
toDate	string <date> End date of the batch
paymentForm	string Enum: "PUE" "PPD" Payment form to filter the batch
taxIdentifier	string Tax identifier to filter the batch
taskType	string Default: "deductibles" Enum: "deductibles" "invoices" The task type for the batch

Responses

Request samples

Payload

Content type

application/json

{"fromDate": "2019-08-24",
"toDate": "2019-08-24",
"paymentForm": "PUE",
"taxIdentifier": "string",
"taskType": "deductibles"
}

Response samples

200

Content type

application/json

{"success": true,
"taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Get deductible sync

Retrieves a list of deductibles syncs

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch deductibles syncs for

Responses

Response samples

200

Content type

application/json

{"fromDateAt": "2019-08-24",
"paymentForm": "PUE",
"taxIdentifier": "string",
"scheduledDays": [0
],
"taskType": "deductibles",
"mode": "every"
}

Create a new deductible sync

Creates a new deductible sync

query Parameters

organization_id

required

string <uuid>

ID of the organization to delete the deductible sync for

Request Body schema: application/json
required

fromDate	string <date> Start date of the sync
scheduledDays	Array of numbers If mode is "on": schedule sync on the days specified in scheduledDays (only values 1, 7, 15, 20, 0 are allowed, 0 representing last day of the month) If mode is "every": schedule sync every X days specified in scheduledDays (only one value between 1 and 30 is allowed)
mode	string Enum: "every" "on" If mode is "on": schedule sync on the days specified in scheduledDays If mode is "every": schedule sync every X days specified in scheduledDays
paymentForm	string Enum: "PUE" "PPD" Payment form to filter the sync
taxIdentifier	string Tax identifier to filter the sync
taskType	string Default: "deductibles" Enum: "deductibles" "invoices" The type of the task the sync will create

Responses

Request samples

Payload

Content type

application/json

{"fromDate": "2019-08-24",
"scheduledDays": [0
],
"mode": "every",
"paymentForm": "PUE",
"taxIdentifier": "string",
"taskType": "deductibles"
}

Response samples

200

Content type

application/json

{"type": null,
"properties": null
}

Delete a deductible sync

Deletes the configured deductible sync for the organization

query Parameters

organization_id required	string <uuid> ID of the organization to delete the deductible sync for
task_type required	any The task type to delete

Responses

Response samples

200

Content type

application/json

{"success": true
}

Get deductible details by ID

Retrieves detailed information about a specific deductible

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible to retrieve

Responses

Response samples

200
401
402
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "processing",
"statusMode": "manual",
"uuid": "string",
"series": "string",
"folioNumber": 0,
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0,
"cfdiUse": "string",
"paymentMethod": "string",
"paymentForm": "string",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"issuerTaxRegime": "string",
"issuerPostalCode": "string",
"isEntity": true,
"recipientName": "string",
"recipientTaxIdentifier": "string",
"recipientTaxRegime": "string",
"recipientPostalCode": "string",
"recipientTaxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"recipientEconomicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"currencyCode": "string",
"isCancelled": true,
"readAt": "2019-08-24T14:15:22Z",
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/xml",
"contentDisposition": "string",
"type": "deductible_xml",
"filename": "string"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"type": "deductible_pdf",
"filename": "string"
},
"pdfFileVerifiedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"issuedAt": "2019-08-24T14:15:22Z",
"stampedAt": "2019-08-24T14:15:22Z",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "601",
"description": "General de Ley Personas Morales"
}
],
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"isDemoMode": false
},
"reasoning": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "processing",
"veredict": "deductible",
"justification": "string",
"confidenceScore": 0,
"ratings": [{"rating": "positive"
}
],
"acceptedAt": "2019-08-24T14:15:22Z",
"rejectedAt": "2019-08-24T14:15:22Z"
},
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"itemKey": "string",
"itemKeyDescription": "string",
"unitKey": "string",
"unitDescription": "string",
"description": "string",
"quantity": 0,
"netUnitPriceAmount": 0,
"netPriceAmount": 0,
"discount": 0,
"status": "deductible",
"statusMode": "manual",
"taxes": [{"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0
}
],
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"reasoning": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"veredict": "deductible",
"justification": "string",
"legalJustification": "string",
"ratings": [{"rating": "positive"
}
],
"acceptedAt": "2019-08-24T14:15:22Z",
"rejectedAt": "2019-08-24T14:15:22Z"
}
}
],
"taxes": [{"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0
}
]
}

Update deductible

Updates a deductible

path Parameters

id

required

string <uuid>

ID of the deductible to update

Request Body schema: application/json
required

notes	string
status	string Enum: "deductible" "review" "not_deductible"
paymentProofFileId	string <uuid>
invoicePdfFileId	string <uuid>
isRead	boolean
chartId	string <uuid>

Responses

Request samples

Payload

Content type

application/json

{"notes": "Notas del deducible",
"status": "deductible",
"paymentProofFileId": "123e4567-e89b-12d3-a456-426614174000",
"invoicePdfFileId": "123e4567-e89b-12d3-a456-426614174000",
"isRead": true,
"chartId": "123e4567-e89b-12d3-a456-426614174000"
}

Response samples

Content type

application/json

{"success": true,
"archived": true
}

Delete deductible

Deletes a deductible

path Parameters

id

required

string <uuid>

ID of the deductible to delete

query Parameters

convert_to_invoice

boolean

Default: false

If set to 'true', the deductible will be converted to an Invoice and a new entry for a Provider prospect will be created (if it didn't exist yet) for this organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Generate PDF for deductible

Generates a PDF for a deductible

path Parameters

id

required

string <uuid>

ID of the deductible to generate PDF for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}

Get providers list from deductibles

Retrieves a list of providers from all deductibles of the organization

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch providers for

Responses

Response samples

200
400
401

Content type

application/json

[{"issuerName": "string",
"issuerTaxIdentifier": "string"
}
]

Get product keys list from deductibles

Retrieves a list of product keys from all deductibles of the organization

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch product keys for

Responses

Response samples

200
400
401

Content type

application/json

[{"productKey": "string",
"productKeyDescription": "string"
}
]

Get payment forms list from deductibles

Retrieves a list of payment forms from all deductibles of the organization

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch payment forms for

Responses

Response samples

200
400
401

Content type

application/json

[{"code": "string",
"description": "string",
"priority": 0
}
]

Get payment methods list from deductibles

Retrieves a list of payment methods from all deductibles of the organization

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch payment methods for

Responses

Response samples

200

Content type

application/json

[{"code": "string",
"description": "string"
}
]

Get CFDI uses list from deductibles

Retrieves a list of CFDI uses from all deductibles of the organization

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch CFDI usees for

Responses

Response samples

200
400
401

Content type

application/json

[{"code": "string",
"description": "string",
"priority": 0
}
]

Get entity types list from deductibles

Retrieves a list of entity types from all deductibles of the organization

query Parameters

organization_id

string <uuid>

ID of the organization to fetch entity types for

Responses

Response samples

200
400
401

Content type

application/json

[{"isEntity": true
}
]

Download deductibles as a zip or xls file

Downloads a zip or xls file containing all selected deductibles

Authorizations:

OAuth2

query Parameters

format required	string Enum: "zip" "xls" Format of the file to download
deductible_ids	string Comma separated list of IDs of the deductibles to download. If this parameter is specified, all other query filters (except 'format') will be ignored.
organization_id	string <uuid> ID of the organization to fetch deductibles for
uuid	string <uuid> Filter by deductible UUID
statuses	string Example: statuses=deductible,not_deductible,not_valid Comma-separated list of deductible statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
created_at_period	string Example: created_at_period=2025-01 Filter deductibles created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter deductibles issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter deductibles stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter deductibles created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter deductibles issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter deductibles stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
is_entity	boolean Default: false Filter by entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Deductible Items

Update deductible item

Updates a deductible item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible item to update

Request Body schema: application/json
required

status	string Enum: "deductible" "review" "not_deductible"
chartId	string or null <uuid> ID of the chart to assign to the deductible item.
chartReasoningConfirmed	boolean Used to mark when a human has confirmed the chart reasoning.

Responses

Request samples

Payload

Content type

application/json

{"status": "deductible",
"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"chartReasoningConfirmed": true
}

Response samples

Content type

application/json

{"success": true,
"message": "Deductible item updated successfully"
}

Deductible Rules

Get deductible rules

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch deductible rules for
sort	string Default: "priority" Enum: "description" "priority" "createdAt" "updatedAt" Field to sort by
order	string Default: "asc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Enum: 10 30 60 100 Number of items per page

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"isEnabled": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"page": 0,
"pageSize": 0,
"total": 0
}

Enable or disable a deductible rule

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible rule to enable or disable

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch deductible rules for

Request Body schema: application/json
required

isEnabled

boolean

Responses

Request samples

Payload

Content type

application/json

{"isEnabled": true
}

Response samples

Content type

application/json

{"success": true
}

Deductible Reasons

Create a new deductible reason

Authorizations:

OAuth2

Request Body schema: application/json
required

Array

deductibleId

string <uuid>

ID of the deductible

Responses

Request samples

Payload

Content type

application/json

[{"deductibleId": "fd8f0c3d-b38b-4018-a0a8-4def4cac471b"
}
]

Response samples

Content type

application/json

{"success": true
}

Accept or reject a deductible reason

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible reason to accept or reject

Request Body schema: application/json
required

status	string Enum: "deductible" "not_deductible"
notes	string

Responses

Request samples

Payload

Content type

application/json

{"status": "deductible",
"notes": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Accept or reject a deductible item reason

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible item reason to accept or reject

Request Body schema: application/json
required

status	string Enum: "deductible" "not_deductible"
notes	string

Responses

Request samples

Payload

Content type

application/json

{"status": "deductible",
"notes": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Rate a deductible item reason

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible item reason to rate

Request Body schema: application/json
required

rating

string

Enum: "positive" "negative" "neutral"

Rating of the deductible item reason

Responses

Request samples

Payload

Content type

application/json

{"rating": "positive"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Rate a deductible reason

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the deductible reason to rate

Request Body schema: application/json
required

rating

string

Enum: "positive" "negative" "neutral"

Rating of the deductible reason

Responses

Request samples

Payload

Content type

application/json

{"rating": "positive"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Consumables

Get consumables

Get consumables of the organization for the period

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch consumables for
period	string Period to query the consumables. If not provided, the consumables for the current period are returned.

Responses

Response samples

200
400
401
403

Content type

application/json

[{"consumableKey": "stamp",
"count": 0,
"limit": 0,
"period": "monthly",
"pricePerUnit": 0
}
]

Get consumable consumptions

Get consumable consumptions of the organization with filtering capabilities.

Default mode: Returns a paginated list of consumable consumptions with sorting.

Aggregate mode (when aggregate=true): Returns aggregated totals (count, amount) and a breakdown by consumable key (byConsumableKey). Pagination and sorting parameters are ignored.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch consumable consumptions for
aggregate	boolean Default: false When true, returns aggregated totals (count, amount) and byConsumableKey breakdown instead of a paginated list. Pagination and sorting parameters are ignored.
page	integer >= 1 Default: 1 Page number for pagination (default is 1). Ignored when aggregate=true.
limit	integer [ 1 .. 100 ] Default: 30 Number of items per page (default is 30). Ignored when aggregate=true.
sort	string Default: "createdAt" Enum: "createdAt" "count" "unitPrice" "consumableKey" Field to sort by. Ignored when aggregate=true.
order	string Default: "desc" Enum: "asc" "desc" Sort order. Ignored when aggregate=true.
created_at_from	string <date-time> Filter consumable consumptions created from this date (ISO 8601 format)
created_at_to	string <date-time> Filter consumable consumptions created up to this date (ISO 8601 format)
consumable_key	string Filter by consumable key (case-insensitive partial match)
mode	string Enum: "balance" "included" "lowConfidenceScore" Filter by consumption mode
q	string Filter by folioNumber

Responses

Response samples

200
400
401
403

Content type

application/json

{"count": 0,
"amount": 0,
"byConsumableKey": [{"consumableKey": "string",
"count": 0,
"amount": 0
}
]
}

Charts

Get charts

Get charts of the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch charts for

Responses

Response samples

200
400
401
402

Content type

application/json

{"charts": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string",
"children": [{ }
]
}
],
"lastUpdatedAt": "2019-08-24T14:15:22Z"
}

Upload a XLS file to update the charts of the organization

Uploads and processes a XLS file to update the charts of the organization. The file must have the following structure:

Column A: Code
Column B: Description (optional)

Authorizations:

OAuth2

query Parameters

organization_id required	any ID of the organization to update the charts for
mode	string Default: "update" Enum: "update" "replace" Mode of the operation

Request Body schema: multipart/form-data
required

file

required

string <binary>

The file to upload

Responses

Response samples

200
400
401
403

Content type

application/json

{"success": true,
"updatedCharts": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string",
"children": [{ }
]
}
],
"updateCount": 10
}

Delete charts

Delete charts of the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to delete charts for

Responses

Response samples

200
401
403

Content type

application/json

{"success": true
}

Get items that need chart classification

Returns items (invoice items, deductible items, expense items) that need chart classification.

By default, returns items that have no chart assigned. When max_confidence_score is provided, also includes items that have a chart assigned with 'reasoning' mode but with a confidence score at or below the threshold (indicating they may need reclassification).

Items with 'reasoning' mode that have already been confirmed by a human (chartReasoningConfirmedAt or chartAsPayableReasoningConfirmedAt is not null) are excluded from the results, as they no longer need classification.

This endpoint is useful for building a queue of items that need human review for chart assignment.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch items for
page	integer >= 1 Default: 1 Page number for pagination (1-based)
limit	integer [ 1 .. 100 ] Default: 10 Number of items per page
type	string Enum: "invoice" "invoice_as_provider" "deductible" "expense" Filter by item type
max_confidence_score	number <float> [ 0 .. 1 ] Example: max_confidence_score=0.5 Maximum confidence score threshold. When provided, also returns items that have a chart assigned with 'reasoning' mode but with confidence score at or below this value. Items with 'manual' or 'reinforcement' mode are excluded from this filter.
min_confidence_score	number <float> [ 0 .. 1 ] Example: min_confidence_score=0.8 Minimum confidence score threshold. When provided, only returns items that have a chart assigned with confidence score at or above this value. Uses the higher of chartConfidenceScore or chartAsPayableConfidenceScore for comparison.
include_assigned	boolean Default: false Example: include_assigned=true If true, includes all items regardless of chart assignment status. When false (default), only returns items that need classification (no chart assigned or low confidence reasoning charts).

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "invoice",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
"issuerName": "string",
"recipientName": "string",
"description": "string",
"grossPriceAmount": 0,
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
},
"chartMode": "manual",
"chartConfidenceScore": 0,
"chartReasoningConfirmedAt": "2019-08-24T14:15:22Z",
"chartAsPayable": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
},
"chartAsPayableMode": "manual",
"chartAsPayableConfidenceScore": 0,
"chartAsPayableReasoningConfirmedAt": "2019-08-24T14:15:22Z"
}
],
"pagination": {"page": 0,
"pageSize": 0,
"total": 0,
"totalPages": 0
}
}

Get concepts that need chart classification

Returns concepts that need chart classification. Concepts are templates that store item attributes (description, itemKey, issuerName, recipientName) along with their embeddings and chart assignments.

By default, returns concepts that have no chart assigned. When max_confidence_score is provided, also includes concepts that have a chart assigned with 'reasoning' mode but with a confidence score at or below the threshold (indicating they may need reclassification).

When include_assigned is true, returns all concepts regardless of chart assignment status.

This endpoint is useful for building a queue of concepts that need human review for chart assignment.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch concepts for
page	integer >= 1 Default: 1 Page number for pagination (1-based)
limit	integer [ 1 .. 100 ] Default: 10 Number of concepts per page
max_confidence_score	number <float> [ 0 .. 1 ] Example: max_confidence_score=0.5 Maximum confidence score threshold. When provided, also returns concepts that have a chart assigned with 'reasoning' mode but with confidence score at or below this value. Concepts with 'manual' or 'reinforcement' mode are excluded from this filter.
min_confidence_score	number <float> [ 0 .. 1 ] Example: min_confidence_score=0.8 Minimum confidence score threshold. When provided, only returns concepts that have a chart assigned with confidence score at or above this value. Uses the higher of chartConfidenceScore or chartAsPayableConfidenceScore for comparison.
include_assigned	boolean Default: false Example: include_assigned=true If true, includes all concepts regardless of chart assignment status. When false (default), only returns concepts that need classification (no chart assigned or low confidence reasoning charts).
chart_mode_filter	string Enum: "none" "manual" "reasoning" Example: chart_mode_filter=none Filter concepts by chart assignment mode. Valid values: `none`: Returns concepts with no chart assigned whatsoever `manual`: Returns concepts with charts assigned by 'manual' or 'reinforcement' mode `reasoning`: Returns concepts with charts assigned by 'reasoning' mode
type	string Enum: "invoice" "invoice_as_provider" "deductible" "expense" Example: type=invoice Filter concepts by type. Valid values: `invoice`: Returns invoice concepts where the organization is the recipient (provider_id != organization_id or provider_id is null) `invoice_as_provider`: Returns invoice concepts where the organization is the provider (provider_id = organization_id) `deductible`: Returns deductible concepts `expense`: Returns expense concepts Note: In the database, concepts only have "invoice" as type, but when provider_id matches organization_id, they are returned as "invoice_as_provider" in the response.
category	string Enum: "sat" "foreign" "government" "payment_notice" Example: category=sat Filter invoice concepts by category. Only applies to invoice concepts (type = 'invoice' or 'invoice_as_provider'). Non-invoice concepts (deductible, expense) are not affected by this filter.
description	string Example: description=servicio Filter concepts by description. Performs a case-insensitive partial match search on the concept description. If provided, only concepts whose description contains the specified text (case-insensitive) will be returned.

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "invoice",
"description": "string",
"itemKey": "string",
"issuerName": "string",
"recipientName": "string",
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
},
"chartMode": "manual",
"chartConfidenceScore": 0,
"chartReasoningAt": "2019-08-24T14:15:22Z",
"chartAsPayable": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
},
"chartAsPayableMode": "manual",
"chartAsPayableConfidenceScore": 0,
"chartAsPayableReasoningAt": "2019-08-24T14:15:22Z",
"itemCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"pagination": {"page": 0,
"pageSize": 0,
"total": 0,
"totalPages": 0,
"totalItems": 0
}
}

Get count of items that can be reclassified for a concept

Returns the count of items that match this concept and can be reclassified when a chart is manually assigned to the concept. This includes:

Items with 'reasoning' chartMode (or chartAsPayableMode for invoices) that would be updated
Items with no chart assigned (chartId is null) or no chartAsPayable assigned (chartAsPayableId is null)

The response also provides a breakdown by confidence score threshold (0.8):

Items below the threshold (confidence < 0.8 or null) - these are items that were previously assigned with low confidence or have no chart assigned
Items above the threshold (confidence >= 0.8) - these are items that were previously assigned with high confidence but are in 'reasoning' mode

This endpoint is useful for showing users how many items would be affected if they manually assign a chart to a concept, and which items were previously below or above the confidence threshold.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the concept

Responses

Response samples

200
400
401
404
500

Content type

application/json

{"chartCount": 0,
"chartAsPayableCount": 0,
"totalCount": 0,
"chartCountBelowThreshold": 0,
"chartCountAboveThreshold": 0,
"chartAsPayableCountBelowThreshold": 0,
"chartAsPayableCountAboveThreshold": 0,
"hasEnoughBalance": true,
"consumablesToConsume": 0,
"actualUnitsToDebit": 0,
"amountToDebit": 0
}

Update concept chart assignments

Updates chart assignments for a concept. Can assign or update charts, and can confirm reasoning for charts assigned with 'reasoning' mode.

When assigning a chart:

If no chart was assigned before, sets chartMode to 'manual'
If chart was assigned with 'reasoning' mode, sets chartMode to 'reinforcement'
Otherwise, sets chartMode to 'manual'

When a chart (or chartAsPayable) is assigned to a concept, all matching items that can be reclassified are automatically updated:

Items with 'reasoning' chartMode (or chartAsPayableMode) are updated with the new chart assignment
Items with no chart assigned (chartId is null) or no chartAsPayable assigned (chartAsPayableId is null) are updated with the new chart assignment

For invoice concepts:

chartId is assigned by providerId (organization acting as provider)
chartAsPayableId is assigned by organizationId (organization acting as recipient)

For deductible/expense concepts:

chartId is assigned by organizationId

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the concept to update

Request Body schema: application/json
required

chartId	string or null <uuid> Chart ID to assign. Set to null to remove the chart assignment.
chartAsPayableId	string or null <uuid> Chart as payable ID to assign (only for invoice concepts). Set to null to remove the assignment.
chartReasoningConfirmed	boolean Set to true to confirm the reasoning for the chart. Can only be set when chartMode is 'reasoning' and chartId is not null. Cannot be set when chartId is being updated simultaneously.
chartAsPayableReasoningConfirmed	boolean Set to true to confirm the reasoning for the chart as payable. Can only be set when chartAsPayableMode is 'reasoning' and chartAsPayableId is not null. Cannot be set when chartAsPayableId is being updated simultaneously.

Responses

Request samples

Payload

Content type

application/json

{"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"chartAsPayableId": "e5cbc150-426d-4c07-8f16-2678e9338d6e",
"chartReasoningConfirmed": true,
"chartAsPayableReasoningConfirmed": true
}

Response samples

Content type

application/json

{"success": true,
"itemsUpdated": 8,
"chartItemsUpdated": 5,
"chartAsPayableItemsUpdated": 3
}

Contact

Submit feedback from the portal

Sends feedback from an authenticated user to the Tatem contact address. Requires the user to belong to the given organization. The contact email receives the feature, organization name, user name, comments, and date/time. The user receives a "Gracias por contactarnos" confirmation email on success.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization context for this feedback (user must have access)

Request Body schema: application/json
required

feature required	string Open text describing the feature or area (e.g. Facturación, Reportes). Filled in by the frontend.
comments required	string User's feedback or comments.

Responses

Request samples

Payload

Content type

application/json

{"feature": "Facturación",
"comments": "Sería útil poder filtrar por fecha de emisión."
}

Response samples

Content type

application/json

{"ok": true
}

Notifications

Get notifications token

Retrieves the authenticated user's notifications token

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Responses

Response samples

200
400
401
403
500

Content type

application/json

{"keyName": "kQII_Q._NT4GA",
"clientId": "cm8s41v8g000xyybohttlxeu2",
"capability": "{\"org:a4897663-13e8-4e60-94ad-b97bfc29fdcc:notifications\":[\"subscribe\"]}",
"timestamp": 1744874357402,
"nonce": "8850976877819143",
"mac": "cRVhv3/+a2BucuMHBQlVLQyJvGYVQlORDoP8gQ/93CQ="
}

Get user notifications

Retrieves the authenticated user's notifications

Authorizations:

OAuth2

Responses

Response samples

200
400
401
403

Content type

application/json

[{"id": "abcd",
"event": "organization_basic_data_verification_success",
"payload": {"id": "abcd",
"status": "valid"
},
"createdAt": "2024-12-01T17:24:59.146Z",
"organization": {"id": "abcd",
"name": "Organization Name",
"commercialName": "Organization Commercial Name",
"taxIdentifier": "1234567890"
},
"users": [{"createdAt": "2024-12-01T17:24:59.146Z"
}
]
}
]

Mark notifications as read

Marks the specified notifications as read

Authorizations:

OAuth2

Request Body schema: application/json
required

Array

notificationId

required

string

Responses

Request samples

Payload

Content type

application/json

[{"notificationId": "abcd"
}
]

Response samples

200
400
401
403
500

Content type

application/json

{"success": true,
"count": 1
}

Clear notifications

Clear the specifiednotifications

Authorizations:

OAuth2

Request Body schema: application/json
required

Array

notificationId

required

string

Responses

Request samples

Payload

Content type

application/json

[{"notificationId": "abcd"
}
]

Response samples

200
400
401
403
500

Content type

application/json

{"success": true,
"count": 1
}

Status

Get status

Responses

Response samples

200

Content type

application/json

{"daysSinceLastSync": 10,
"syncLastResponseAt": "2025-06-15T12:00:00.000Z"
}

Stats

Get home statistics

Retrieves basic statistics including counts of providers, expenses, invoices, foreign invoices, reasoned items, and government invoices.

Responses

Response samples

200

Content type

application/json

{"stats": {"numberOfProviders": 150,
"numberOfExpenses": 1250,
"numberOfForeignInvoices": 45,
"numberOfReasonedItems": 320,
"numberOfGovernmentInvoices": 0,
"numberOfInvoices": 2100
}
}

Trusted Devices

Create a trusted device

Authorizations:

OAuth2

Responses

Response samples

200
401

Content type

application/json

{"success": true,
"deviceId": "123e4567-e89b-12d3-a456-426614174000"
}

Provider Prospects

Get provider prospects for an organization

Retrieves a list of provider prospects for the specified organization

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch provider prospects for
q	string Filter by name, commercialName or taxIdentifier
name	string Name of the provider prospect
taxIdentifier	string Tax identifier of the provider prospect
commercialName	string Commercial name of the provider prospect
isInEfos	boolean Default: null Whether the provider prospect is in Efos
incomplete	boolean Default: null Filter by incomplete provider prospects according to the organization's invoice preferences
duplicates	boolean Filter by duplicate provider prospects. If true, only prospects with isDuplicateOfId set are returned. If false, only prospects without isDuplicateOfId are returned. Omit for no filter.
sort	string Default: "name" Enum: "name" "taxIdentifier" "organization.status" "createdAt" "organizations.isMain" Field(s) to sort by, comma separated
order	string Default: "asc" Enum: "asc" "desc" Sort order for each field specified in 'sort', comma separated. Must be the same number of values as 'sort', otherwise an HTTP 400 'mismatched_sort_order_length' will be returned.
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Enum: 10 30 60 100 Number of items per page

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"isDuplicateOfId": "b119a866-febc-4274-8f9c-6700fb133535",
"invoicesCount": 0,
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"status": "verified",
"managedByOrganization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
},
"bankAccounts": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"organizationsAsProviders": {"creditDays": 30,
"creditPeriod": "d",
"bankAccount": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"referenceNumber": "string",
"bankAccountInstructionsFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
},
"taxIdentificationDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"taxIdentificationDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"complianceDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"complianceDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
},
"organizations": [{"isMain": true
}
]
}
],
"notVerifiedCount": 0,
"incompleteCount": 0,
"mainCount": 0,
"duplicateCount": 0,
"grossPriceAmount": 0,
"numberOfInvoices": 0,
"totalPages": 0,
"totalCount": 0
}

Update main provider prospects list

Updates the main provider prospects list for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to update provider prospects for

Request Body schema: application/json
required

providerProspectIds	Array of strings <uuid> [ items <uuid > ]
isMain	boolean Whether to set the provider prospects as main or not
allowDisable	boolean When the number of main provider prospects is exceeded for the organization, setting this value to true will allow to automatically disable other provider prospects with the less amount of existing invoices.

Responses

Request samples

Payload

Content type

application/json

{"providerProspectIds": [["123e4567-e89b-12d3-a456-426614174000",
"987fcdeb-51a2-43d1-b789-123456789abc"
]
],
"isMain": true,
"allowDisable": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"providerProspectsToDisable": [{"name": "string",
"taxIdentifier": "string",
"organization": {"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
}
}
],
"providerProspectsToEnable": [{"name": "string",
"taxIdentifier": "string",
"organization": {"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
}
}
]
}

Deduplicate provider prospects

Runs deduplication for the organization's provider prospects.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to run deduplication for

Responses

Response samples

200
400
401

Content type

application/json

{"ok": true
}

Download provider prospects as Excel

Downloads a list of provider prospects for the specified organization as an Excel file.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to download provider prospects for
provider_prospect_ids	string Comma separated list of provider prospect ids to include in the downloaded Excel file. If no ids are provided, all providers are included.

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Get a provider prospect

Retrieves a provider prospect by ID

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the provider prospect to fetch

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch provider prospect for

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"providerProspect": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"isDuplicateOfId": "b119a866-febc-4274-8f9c-6700fb133535",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"addressStreet": "string",
"addressNumber": "string",
"addressNumberInterior": "string",
"addressNeighborhood": "string",
"addressCity": "string",
"addressMunicipality": "string",
"addressState": "string",
"postalCode": "string",
"status": "verified",
"bankId": "string",
"bankIdentifier": "string",
"facturapiValidatedAt": "2019-08-24T14:15:22Z",
"facturapiValidationErrors": "string",
"taxIdentificationDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"taxIdentificationDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"complianceDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"complianceDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"contactFirstName": "Juan",
"contactLastName": "Pérez",
"contactEmailAddress": "juan.perez@example.com",
"contactPhoneNumber": "525512345678",
"contactJobTitle": "Gerente General",
"beneficiaryName": "Juan Pérez",
"managedByOrganization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
}
},
"organizations": [{"isMain": true
}
]
},
"amountPaid": 0,
"numberOfInvoicesPaid": 0,
"numberOfInvoicesPending": 0
}

Create a new organization for a provider prospect

Creates a new organization for a provider prospect

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the provider prospect

query Parameters

organization_id

required

string <uuid>

ID of the organization creating the new organization for the provider prospect

Request Body schema: application/json
required

commercialName	string Commercial/trading name of the organization
industry	string Industry of the organization

Responses

Request samples

Payload

Content type

application/json

{"commercialName": "string",
"industry": "string"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"isEntity": true,
"industry": "string",
"status": "pending",
"avatarUrl": "https://example.com/avatar.jpg"
}
}

Organization Prospects

Get organization prospects for a provider

Retrieves a list of organization prospects for the specified provider

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch provider prospects for
q	string Filter by name, commercialName or taxIdentifier
sort	string Default: "name" Enum: "name" "taxIdentifier" "organization.status" "createdAt" Field to sort by
order	string Default: "asc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Enum: 10 30 60 100 Number of items per page

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"commercialName": "string",
"status": "verified",
"taxIdentificationDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"taxIdentificationDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"complianceDocumentVerifiedAt": "2019-08-24T14:15:22Z",
"complianceDocumentFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"url": "http://example.com"
},
"organizationsAsOrganizations": [{"creditDays": 30,
"creditPeriod": "d",
"bankAccount": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"referenceNumber": "string",
"bankAccountInstructionsFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"provider": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"bankAccounts": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}
}
],
"totalPages": 0,
"totalCount": 0
}

Invoices

Get invoices list

Retrieves a paginated list of invoices with optional filters

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890,1234567891 Comma separated list of folio numbers to filter by
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
paid_at_from	string <date-time> Filter invoices by the paid date of their related Payment (inclusive start)
paid_at_to	string <date-time> Filter invoices by the paid date of their related Payment (inclusive end)
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
sort	string Default: "statusCode" Enum: "uuid" "grossPriceAmount" "organization.taxIdentifier" "organization.name" "issuerName" "recipientName" "status" "statusCode" "sentAt" "createdAt" "updatedAt" "paymentDueAt" "stampedAt" "folioNumber" "series" Comma-separated list of fields to sort by
order	string Default: "asc" Enum: "asc" "desc" Comma-separated list of sort orders to sort by. The number of values in this parameter must match exactly the number of values in the 'order' parameter.
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 30 Enum: 10 30 60 100 Number of items per page
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD,PUE Filter by payment methods, comma separated
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Filter by cancelled status

Responses

Response samples

200
400
401

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"folioNumber": "1234567890",
"series": "S",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"commercialName": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"provider": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"category": "sat",
"paymentMethod": "PPD",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"recipientName": "string",
"recipientTaxIdentifier": "string",
"status": "draft",
"sentAt": "2024-12-01T17:24:59.146Z",
"createdAt": "2024-12-01T17:24:59.146Z",
"updatedAt": "2024-12-01T17:24:59.146Z",
"issuedAt": "2024-12-01T17:24:59.146Z",
"stampedAt": "2024-12-01T17:24:59.146Z",
"netPriceAmount": 0,
"grossPriceAmount": 0,
"isCancelled": false,
"isPending": false,
"readAt": "2024-12-01T17:24:59.146Z",
"items": [{"description": "Factura por pagar",
"quantity": 1,
"unitKey": "unit",
"unitDescription": "Unidad",
"itemKey": "item",
"discount": 10
}
],
"paymentDueAt": "2024-12-01T17:24:59.146Z",
"isDemo": true,
"paymentProof": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
},
"payments": [{"payment": {"status": "pending",
"paidAt": "2024-12-01T17:24:59.146Z",
"paymentProofFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"paymentReceipt": {"paymentReceiptFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}
}
}
],
"invoicePayments": [{"invoicePayment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}
}
],
"isGeneric": true,
"annotationsProvider": "string",
"annotationsOrganization": "string",
"originalCurrencyCode": "string",
"itemCount": 0,
"itemsWithChartCount": 0,
"itemsWithChartAsPayableCount": 0
}
],
"totalPages": 0,
"totalCount": 0,
"unreadCount": 0,
"amountDue": 0,
"amountPastDue": 0,
"amountPaid": 0,
"countDue": 0,
"countPastDue": 0,
"countPaid": 0
}

Create a new invoice

Creates a new invoice by uploading XML and PDF files

Authorizations:

OAuth2

query Parameters

provider_id	string <uuid> ID of the provider creating the invoice
organization_id	string <uuid> ID of the organization the invoice is for

Request Body schema: multipart/form-data
required

invoiceXml required	string <binary> XML file containing the CFDI invoice data
invoicePdf	string <binary> PDF version of the invoice
purchaseOrderPdf	string <binary> Optional PDF or image file of the purchase order

Responses

Response samples

Content type

application/json

{"success": false,
"invitationCode": "string",
"organization": {"id": "string",
"taxIdentifier": "string",
"name": "string",
"commercialName": "string"
}
}

Update invoices

Updates a list of invoices

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Default: false Filter by cancelled status

Request Body schema: application/json
optional

invoiceIds	Array of strings <uuid> <= 100 items [ items <uuid > ] IDs of the invoices to update. If this parameter is specified, query filters will be ignored.
archive	boolean Whether to archive (true) or unarchive (false) the invoice. All the invoices must be in 'rejected' or 'completed' status, otherwise the service will return an HTTP 400 with error: 'invalid_invoice_status'
paymentDay	number Enum: 1 2 3 If set, the updated invoices will change its paymentDueAt date to the next weekday specified in the invoice preferences of the organization. All the invoices must be in 'accepted' status, otherwise the service will return an HTTP 400 with error: 'invalid_invoice_status'. Also, the invoice must belong to an organization, otherwise the service will return an HTTP 400 with error: 'invoice_doesnt_belong_to_an_organization' The organization must had set its invoice preferences, otherwise the service will return an HTTP 400 with error: 'invoice_preferences_not_found' The invoice preferences must have had set the value 'paymentDay' previously, otherwise the service will return an HTTP 400 with error: 'payment_day_not_set'
paymentDueAt	string <date> When payment is due, in Mexico timezone. All the invoices must be in 'accepted' status, otherwise the service will return an HTTP 400 with error : 'invalid_invoice_status'
paymentDueAtUpdateReason	string Enum: "manual" "payment_proof" "payment_proof_reason" Reason for updating the payment due date. Can only be provided if paymentDueAt is also provided, otherwise it will return a 400 error (payment_due_at_update_reason_requires_payment_due_at). Must be a valid update reason value, otherwise it will return a 400 error (invalid_update_reason).
isRead	boolean

Responses

Request samples

Payload

Content type

application/json

{"invoiceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"archive": true,
"paymentDay": 1,
"paymentDueAt": "2025-01-01",
"paymentDueAtUpdateReason": "manual",
"isRead": true
}

Response samples

Content type

application/json

{"success": true
}

Upload invoices zip

Uploads a zip file containing invoices. The zip file must contain XML files.

Authorizations:

OAuth2

query Parameters

provider_id required	string <uuid> ID of the provider to upload invoices for
organization_id	string <uuid> ID of the organization to upload invoices for

Request Body schema: application/json
required

invoicesUploadZipId required	string <uuid>
createOrganizationProspects	boolean Default: false
createProducts	boolean Default: false

Responses

Request samples

Payload

Content type

application/json

{"invoicesUploadZipId": "bbcf8dbf-9e11-41cf-a06b-8a7388f2d310",
"createOrganizationProspects": false,
"createProducts": false
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"message": "File uploaded successfully"
}

Apply credit note to invoice

Applies a credit note to an invoice. Reduces the invoice's grossPriceAmount by the credit note amount and sets the credit note status to APPLIED. Constraints:

Invoice must be in a non-paid status (not PAID, not COMPLETED)
Invoice must have category 'sat'
Invoice grossPriceAmount must be >= credit note grossPriceAmount
Credit note must be in VALID status

Authorizations:

OAuth2

path Parameters

invoiceId

required

string

Invoice ID

Request Body schema: application/json
required

creditNoteId

required

string

Credit note ID to apply

Responses

Request samples

Payload

Content type

application/json

{"creditNoteId": "string"
}

Response samples

200
400

Content type

application/json

{"success": true,
"invoice": {"id": "string"
},
"creditNote": {"id": "string"
}
}

Get invoices balance

Retrieves the balance of invoices with optional filters

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Default: false Filter by cancelled status

Responses

Response samples

200
400
401

Content type

application/json

{"grossPriceAmount": 1000,
"count": 100
}

Stamp an invoice

Stamps an invoice with the provided data using FacturaAPI. Requires provider_id query parameter and valid authentication.

query Parameters

provider_id

required

string

ID of the provider organization that will stamp the invoice

Request Body schema: application/json
required

required	object
required	Array of objects [ 1 .. 5000 ] items
paymentForm required	string Payment form code
cfdiUse required	string CFDI use code
paymentMethod required	string Payment method code
folioNumber	string <= 25 characters Invoice folio number (optional)
series	string Invoice series (optional)

Responses

Request samples

Payload

Content type

application/json

{"recipient": {"name": "string",
"taxIdentifier": "stringstring",
"taxRegime": "string",
"postalCode": "strin",
"addressStreet": "string",
"addressNumber": "string",
"addressNumberInterior": "string",
"addressCity": "string",
"addressMunicipality": "string",
"addressState": "string"
},
"items": [{"description": "string",
"productKey": "string",
"unitKey": "string",
"unitKeyDescription": "string",
"netUnitPriceAmount": 0,
"taxes": [{"taxId": "string",
"rate": 0
}
],
"quantity": 0,
"discount": 0
}
],
"paymentForm": "string",
"cfdiUse": "string",
"paymentMethod": "string",
"folioNumber": "string",
"series": "string"
}

Response samples

Content type

application/json

{"success": true,
"invoice": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "draft",
"uuid": "string",
"series": "string",
"folioNumber": 0,
"netPriceAmount": 0,
"grossPriceAmount": 0,
"grossPriceAmountUpdateReason": "manual",
"grossPriceAmountUpdatedAt": "2019-08-24T14:15:22Z",
"originalNetPriceAmount": 0,
"originalGrossPriceAmount": 0,
"originalGrossPriceAmountUpdatedAt": "2019-08-24T14:15:22Z",
"originalGrossPriceAmountUpdateReason": "manual",
"originalCurrencyCode": "string",
"discount": 0,
"cfdiUse": "string",
"category": "sat",
"processingMode": "xml",
"paymentMethod": "string",
"paymentForm": "string",
"paymentCode": "string",
"paymentProof": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pdfProcessingPrice": 0
},
"issuerName": "string",
"issuerTaxIdentifier": "string",
"issuerTaxRegime": "string",
"issuerTaxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"issuerEconomicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"issuerPostalCode": "string",
"issuerCountry": "string",
"issuerAddressStreet": "string",
"issuerAddressNumber": "string",
"issuerAddressNumberInterior": "string",
"issuerAddressNeighborhood": "string",
"issuerAddressCity": "string",
"issuerAddressMunicipality": "string",
"issuerAddressState": "string",
"issuerIsEntity": true,
"recipientName": "string",
"recipientTaxIdentifier": "string",
"recipientTaxRegime": "string",
"recipientTaxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"recipientEconomicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"recipientPostalCode": "string",
"recipientIsEntity": true,
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/xml",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "invoice_xml",
"filename": "string",
"url": "http://example.com"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "invoice_pdf",
"filename": "string",
"url": "http://example.com"
},
"pdfFileVerifiedAt": "2019-08-24T14:15:22Z",
"purchaseOrderFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "purchase_order_pdf",
"filename": "string",
"url": "http://example.com"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"sentAt": "2019-08-24T14:15:22Z",
"issuedAt": "2019-08-24T14:15:22Z",
"acceptedAt": "2019-08-24T14:15:22Z",
"stampedAt": "2019-08-24T14:15:22Z",
"paymentDueAt": "2019-08-24T14:15:22Z",
"paymentDueAtUpdateReason": "manual",
"paymentDueAtUpdatedAt": "2019-08-24T14:15:22Z",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"isEntity": true,
"isDemoMode": true,
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"provider": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"isEntity": true,
"isDemoMode": true,
"bankId": "string",
"bankIdentifier": "string"
},
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"itemKey": "string",
"itemKeyDescription": "string",
"unitKey": "string",
"unitDescription": "string",
"description": "string",
"quantity": 0,
"netUnitPriceAmount": 0,
"originalNetUnitPriceAmount": 0,
"netPriceAmount": 0,
"originalNetPriceAmount": 0,
"originalGrossPriceAmount": 0,
"taxes": [{"id": "string",
"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0,
"originalValue": 0
}
],
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"chartMode": "manual",
"chartConfidenceScore": 0,
"chartAsPayable": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"chartAsPayableMode": "manual",
"chartAsPayableConfidenceScore": 0,
"discount": 0
}
],
"taxes": [{"id": "123e4567-e89b-12d3-a456-426614174000",
"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0,
"originalValue": 0
}
],
"localTaxes": [{"name": "string",
"baseAmount": 0,
"rate": 0,
"value": 0
}
],
"payments": [{"payment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "valid",
"paymentProofFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"paymentReceipt": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"paymentReceiptFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
},
"paymentTrackingNumber": "string",
"paymentReferenceNumber": "string",
"paymentIssuerBankId": "string",
"paymentRecipientBankId": "string",
"paymentRecipientBankIdentifier": "string",
"paymentIsOrderingBank": true,
"paidAt": "2019-08-24T14:15:22Z"
}
}
],
"invoicePayments": [{"invoicePayment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "string",
"status": "processing",
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"providerProspectId": "string",
"isGeneric": true,
"confidenceScore": 0,
"pdfProcessingPrice": 0,
"validationErrors": "string",
"archivedByOrganizationAt": "2019-08-24T14:15:22Z",
"archivedByProviderAt": "2019-08-24T14:15:22Z",
"currencyCode": "string",
"isCancelled": true,
"isPending": false,
"isDemo": true
},
"isValid": true,
"message": "Invoice created successfully"
}

Get top charts for provider

Retrieves a list of top charts for a provider

Authorizations:

OAuth2

query Parameters

provider_id

required

string <uuid>

ID of the provider to fetch top charts for

Responses

Response samples

200
400
401
403
404

Content type

application/json

[{"code": "string",
"description": "string",
"totalAmount": 0,
"invoiceCount": 0
}
]

Get top 5 organizations for provider, or top 5 providers for an organization

Retrieves a list of top 5 organizations for a provider, or top 5 providers for an organization

Authorizations:

OAuth2

query Parameters

provider_id required	string <uuid> ID of the provider to fetch top organizations for
organization_id required	string <uuid> ID of the organization to fetch top providers for

Responses

Response samples

200
400
401
403

Content type

application/json

[{"recipientName": "string",
"recipientTaxIdentifier": "string",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"totalAmount": 0,
"invoiceCount": 0
}
]

Get distinct providers from invoices

Retrieves a list of distinct providers (issuers) from invoices for a given organization. Returns the provider name, tax identifier, and associated organization commercial name if available.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to fetch providers for
q	string Optional search query to filter providers by name, tax identifier, or commercial name (case-insensitive)

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"id": "string",
"name": "string",
"taxIdentifier": "string",
"organization": {"commercialName": "string"
}
}
]
}

Batch invoice import

Imports a batch of invoices

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to import invoices for

Request Body schema: application/json
required

fromDate	string <date>
toDate	string <date>
createOrganizationProspects	boolean
createProducts	boolean

Responses

Request samples

Payload

Content type

application/json

{"fromDate": "2025-01-01",
"toDate": "2025-01-31",
"createOrganizationProspects": true,
"createProducts": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"taskId": "123e4567-e89b-12d3-a456-426614174000"
}

Get invoice details by ID

Retrieves detailed information about a specific invoice

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice to retrieve

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"status": "draft",
"uuid": "string",
"series": "string",
"folioNumber": 0,
"netPriceAmount": 0,
"grossPriceAmount": 0,
"grossPriceAmountUpdateReason": "manual",
"grossPriceAmountUpdatedAt": "2019-08-24T14:15:22Z",
"originalNetPriceAmount": 0,
"originalGrossPriceAmount": 0,
"originalGrossPriceAmountUpdatedAt": "2019-08-24T14:15:22Z",
"originalGrossPriceAmountUpdateReason": "manual",
"originalCurrencyCode": "string",
"discount": 0,
"cfdiUse": "string",
"category": "sat",
"processingMode": "xml",
"paymentMethod": "string",
"paymentForm": "string",
"paymentCode": "string",
"paymentProof": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pdfProcessingPrice": 0
},
"issuerName": "string",
"issuerTaxIdentifier": "string",
"issuerTaxRegime": "string",
"issuerTaxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"issuerEconomicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"issuerPostalCode": "string",
"issuerCountry": "string",
"issuerAddressStreet": "string",
"issuerAddressNumber": "string",
"issuerAddressNumberInterior": "string",
"issuerAddressNeighborhood": "string",
"issuerAddressCity": "string",
"issuerAddressMunicipality": "string",
"issuerAddressState": "string",
"issuerIsEntity": true,
"recipientName": "string",
"recipientTaxIdentifier": "string",
"recipientTaxRegime": "string",
"recipientTaxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"recipientEconomicActivities": [{"economicActivity": "string",
"percentage": 0
}
],
"recipientPostalCode": "string",
"recipientIsEntity": true,
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/xml",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "invoice_xml",
"filename": "string",
"url": "http://example.com"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "invoice_pdf",
"filename": "string",
"url": "http://example.com"
},
"pdfFileVerifiedAt": "2019-08-24T14:15:22Z",
"purchaseOrderFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "purchase_order_pdf",
"filename": "string",
"url": "http://example.com"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"sentAt": "2019-08-24T14:15:22Z",
"issuedAt": "2019-08-24T14:15:22Z",
"acceptedAt": "2019-08-24T14:15:22Z",
"stampedAt": "2019-08-24T14:15:22Z",
"paymentDueAt": "2019-08-24T14:15:22Z",
"paymentDueAtUpdateReason": "manual",
"paymentDueAtUpdatedAt": "2019-08-24T14:15:22Z",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"isEntity": true,
"isDemoMode": true,
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"provider": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"isEntity": true,
"isDemoMode": true,
"bankId": "string",
"bankIdentifier": "string"
},
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"itemKey": "string",
"itemKeyDescription": "string",
"unitKey": "string",
"unitDescription": "string",
"description": "string",
"quantity": 0,
"netUnitPriceAmount": 0,
"originalNetUnitPriceAmount": 0,
"netPriceAmount": 0,
"originalNetPriceAmount": 0,
"originalGrossPriceAmount": 0,
"taxes": [{"id": "string",
"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0,
"originalValue": 0
}
],
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"chartMode": "manual",
"chartConfidenceScore": 0,
"chartAsPayable": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"chartAsPayableMode": "manual",
"chartAsPayableConfidenceScore": 0,
"discount": 0
}
],
"taxes": [{"id": "123e4567-e89b-12d3-a456-426614174000",
"tax": {"code": "string",
"description": "string",
"isWithholding": true
},
"baseAmount": 0,
"rate": 0,
"value": 0,
"originalValue": 0
}
],
"localTaxes": [{"name": "string",
"baseAmount": 0,
"rate": 0,
"value": 0
}
],
"payments": [{"payment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "valid",
"paymentProofFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"paymentReceipt": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"paymentReceiptFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
},
"paymentTrackingNumber": "string",
"paymentReferenceNumber": "string",
"paymentIssuerBankId": "string",
"paymentRecipientBankId": "string",
"paymentRecipientBankIdentifier": "string",
"paymentIsOrderingBank": true,
"paidAt": "2019-08-24T14:15:22Z"
}
}
],
"invoicePayments": [{"invoicePayment": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "string",
"status": "processing",
"xmlFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"providerProspectId": "string",
"isGeneric": true,
"confidenceScore": 0,
"pdfProcessingPrice": 0,
"validationErrors": "string",
"archivedByOrganizationAt": "2019-08-24T14:15:22Z",
"archivedByProviderAt": "2019-08-24T14:15:22Z",
"currencyCode": "string",
"isCancelled": true,
"isPending": false,
"isDemo": true
}

Update invoice

Updates an invoice

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice to update

Request Body schema: application/json
required

notes	string
annotationsProvider	string or null Annotations added by the provider. Can only be updated by users belonging to the provider that issued the invoice.
annotationsOrganization	string or null Annotations added by the organization. Can only be updated by users belonging to the organization that owns the invoice.
isRead	boolean
chartId	string <uuid>
category	string Enum: "sat" "foreign" "government" "payment_notice" Invoice category. Can only be updated if the original category is not 'sat', otherwise it will return a 400 error (cannot_change_category). Must be a valid category value, otherwise it will return a 400 error (invalid_category).
paymentDueAt	string <date> When payment is due, in Mexico timezone. This value can be updated only if the invoice is in 'accepted' status, otherwise it will return a 400 error (invalid_status)
paymentDueAtUpdateReason	string Enum: "manual" "payment_proof" "payment_proof_reason" Reason for updating the payment due date. Can only be provided if paymentDueAt is also provided, otherwise it will return a 400 error (payment_due_at_update_reason_requires_payment_due_at). Must be a valid update reason value, otherwise it will return a 400 error (invalid_update_reason).
cfdiUse	string non-empty CFDI use code. Must be a valid CFDI use. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
paymentForm	string Payment form code. Must be a valid payment form. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
stampedAt	string <date-time> Date and time when the invoice was stamped. Can only be updated if the invoice category is 'not sat', otherwise it will return a 400 error (invalid_payment_method).
folioNumber	string non-empty Folio number of the invoice. Must be at least 1 character long. Can only be updated if the invoice category is 'foreign', otherwise it will return a 400 error (invalid_payment_method).
series	string non-empty Series of the invoice. Must be at least 1 character long. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
paymentCode	string or null Payment code of the invoice. Can be updated for any invoice category.
issuerName	string non-empty Name of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerTaxIdentifier	string non-empty Tax identifier (RFC) of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerPostalCode	string non-empty Postal code of the invoice issuer. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerCountry	string Country code of the invoice issuer. Must be a valid country code. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressStreet	string non-empty Street name of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressNumber	string non-empty Street number of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressNumberInterior	string non-empty Interior number of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressNeighborhood	string non-empty Neighborhood of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressCity	string non-empty City of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressMunicipality	string non-empty Municipality of the invoice issuer's address. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerAddressState	string State code of the invoice issuer's address. Must be a valid Mexican state code. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
issuerTaxRegimes	Array of strings Array of tax regime IDs for the invoice issuer. Each ID must be a valid tax regime ID. Descriptions are automatically filled in from the tax regime data. Can only be updated if the invoice category is not 'sat', otherwise it will return a 400 error (invalid_payment_method).
grossPriceAmount	number > 0 Gross price amount for the invoice. Can only be updated if the invoice category is not 'sat', and status is ACCEPTED, otherwise it will return a 400 error (invalid_payment_method, invalid_currency, or invalid_status).
grossPriceAmountUpdateReason	string Enum: "manual" "payment_proof" "payment_proof_reason" Reason for updating the gross price amount. Can only be provided if grossPriceAmount is also provided, otherwise it will return a 400 error (gross_price_amount_update_reason_requires_gross_price_amount). Must be a valid update reason value, otherwise it will return a 400 error (invalid_update_reason).
originalGrossPriceAmount	number > 0 Original gross price amount in the original currency. Can only be updated if the invoice's originalCurrencyCode is different from currencyCode, the invoice has an exchangeRate, and the status is ACCEPTED, otherwise it will return a 400 error (original_currency_code_must_differ, exchange_rate_required, or invalid_status). When updated, the grossPriceAmount will be automatically recalculated using the exchange rate (grossPriceAmount = originalGrossPriceAmount * exchangeRate), and all original values (originalNetPriceAmount, original taxes, original items, and their taxes) will be recalculated from the converted values. Cannot be provided together with grossPriceAmount, otherwise it will return a 400 error (cannot_provide_both_original_gross_price_amount_and_gross_price_amount).
originalGrossPriceAmountUpdateReason	string Enum: "manual" "payment_proof" "payment_proof_reason" Reason for updating the original gross price amount. Can only be provided if originalGrossPriceAmount is also provided, otherwise it will return a 400 error (original_gross_price_amount_update_reason_requires_original_gross_price_amount). Must be a valid update reason value, otherwise it will return a 400 error (invalid_update_reason). This reason will also be applied to the automatically updated grossPriceAmount.

Responses

Request samples

Payload

Content type

application/json

{"notes": "Notas de la factura",
"annotationsProvider": "Provider annotation text",
"annotationsOrganization": "Organization annotation text",
"isRead": true,
"chartId": "123e4567-e89b-12d3-a456-426614174000",
"category": "foreign",
"paymentDueAt": "2025-01-01",
"paymentDueAtUpdateReason": "manual",
"cfdiUse": "G01",
"paymentForm": "03",
"stampedAt": "2025-01-01T12:00:00Z",
"folioNumber": "12345",
"series": "A",
"paymentCode": "PAY123456",
"issuerName": "Empresa Ejemplo S.A. de C.V.",
"issuerTaxIdentifier": "ABC123456XYZ",
"issuerPostalCode": "01234",
"issuerCountry": "MX",
"issuerAddressStreet": "Av. Reforma",
"issuerAddressNumber": "123",
"issuerAddressNumberInterior": "A",
"issuerAddressNeighborhood": "Centro",
"issuerAddressCity": "Ciudad de México",
"issuerAddressMunicipality": "Miguel Hidalgo",
"issuerAddressState": "DF",
"issuerTaxRegimes": ["601",
"603"
],
"grossPriceAmount": 15000.5,
"grossPriceAmountUpdateReason": "manual",
"originalGrossPriceAmount": 1000,
"originalGrossPriceAmountUpdateReason": "manual"
}

Response samples

Content type

application/json

{"success": true
}

Delete invoice

Deletes an invoice. Only invoices with status 'draft', 'sent', 'accepted', 'rejected', 'processing', 'not_valid', or 'paid' can be deleted.

Convert to expense: When convertToExpense is true, the invoice is converted into an expense before deletion. A new expense is created from the invoice (issuer, items, amounts, PDF if present, and organization annotations copied to expense notes). Only users who belong to the invoice's organization can use convertToExpense; otherwise the API returns HTTP 403 error. When converting to expense, deleteReason is not required. The response includes expenseId with the created expense ID.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice to delete

Request Body schema: application/json
required

deleteReason	string non-empty Reason for deleting the invoice. Required when `convertToExpense` is not true.
convertToExpense	boolean When true, create an expense from the invoice details before deleting the invoice. Only allowed if the user belongs to the invoice's organization. When true, `deleteReason` is optional.

Responses

Request samples

Payload

Content type

application/json

Example

Delete with reason

{"deleteReason": "Invoice was created by mistake"
}

Response samples

Content type

application/json

{"success": true,
"expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc"
}

Download invoice

Downloads a completed invoice. The invoice must be in 'completed' status

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice to download

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Cancel invoice

Cancel an invoice. The invoice must be in 'sent' or 'accepted' status and its payment method must be either 'PPD' or 'PUE'. The cancellation reason is stored on the invoice.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice to cancel

query Parameters

force

boolean

Example: force=true

If set to true, SAT status won't be checked before setting the invoice as cancelled.

Responses

Response samples

Content type

application/json

{"success": true
}

Get product keys list from invoices

Retrieves a list of product keys from all invoices of the organization

query Parameters

organization_id	string <uuid> ID of the organization to fetch product keys for
provider_id	string <uuid> ID of the provider to fetch product keys for

Responses

Response samples

200
400
401

Content type

application/json

[{"productKey": "string",
"productKeyDescription": "string"
}
]

Get payment forms list from invoices

Retrieves a list of payment forms from all invoices of the organization

query Parameters

organization_id	string <uuid> ID of the organization to fetch payment forms for
provider_id	string <uuid> ID of the provider to fetch payment forms for

Responses

Response samples

200
400
401

Content type

application/json

[{"code": "string",
"description": "string",
"priority": 0
}
]

Get payment methods list from invoices

Retrieves a list of payment methods from all invoices of the organization

query Parameters

organization_id	string <uuid> ID of the organization to fetch payment methods for
provider_id	string <uuid> ID of the provider to fetch payment methods for

Responses

Response samples

200

Content type

application/json

[{"code": "string",
"description": "string"
}
]

Get CFDI uses list from invoices

Retrieves a list of CFDI uses from all invoices of the organization

query Parameters

organization_id	string <uuid> ID of the organization to fetch CFDI usees for
provider_id	string <uuid> ID of the provider to fetch CFDI uses for

Responses

Response samples

200
400
401

Content type

application/json

[{"code": "string",
"description": "string",
"priority": 0
}
]

Get entity types list from invoices

Retrieves a list of entity types from all invoices of the organization

query Parameters

organization_id	string <uuid> ID of the organization to fetch entity types for
provider_id	string <uuid> ID of the provider to fetch entity types for

Responses

Response samples

200
400
401

Content type

application/json

[{"isEntity": true
}
]

Download invoices as a zip or xls file

Downloads a zip or xls file containing all selected invoices

Authorizations:

OAuth2

query Parameters

format required	string Enum: "zip" "xls" Format of the file to download
invoice_ids	string Comma separated list of IDs of the invoices to download. If this parameter is specified, all other query filters (except 'format') will be ignored.
organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Default: false Filter by cancelled status

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Create invoice tax

Creates a new global tax for an invoice. Can only be created if the invoice category is not 'sat' and status is 'ACCEPTED'.

Authorizations:

OAuth2

Request Body schema: application/json
required

invoiceId required	string <uuid> ID of the invoice to add the tax to
taxId required	string <uuid> ID of the tax. Must be a valid tax ID.
rate required	number >= 0 Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the invoice's netPriceAmount.

Responses

Request samples

Payload

Content type

application/json

{"invoiceId": "123e4567-e89b-12d3-a456-426614174000",
"taxId": "123e4567-e89b-12d3-a456-426614174001",
"rate": 0.16
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
"taxId": "ec2f3321-4009-45bd-9423-63aa80044823",
"code": "string",
"isWithholding": true,
"baseAmount": 0,
"rate": 0,
"value": 0
}
}

Update invoice tax

Updates an invoice tax. Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED'.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice tax to update

Request Body schema: application/json
required

taxId	string <uuid> ID of the tax. Must be a valid tax ID.
rate	number >= 0 Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the invoice's netPriceAmount.

Responses

Request samples

Payload

Content type

application/json

{"taxId": "123e4567-e89b-12d3-a456-426614174001",
"rate": 0.16
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
"taxId": "ec2f3321-4009-45bd-9423-63aa80044823",
"code": "string",
"isWithholding": true,
"baseAmount": 0,
"rate": 0,
"value": 0
}
}

Delete invoice tax

Deletes an invoice tax. Can only be deleted if the invoice category is not 'sat' and status is 'ACCEPTED'.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice tax to delete

Responses

Response samples

Content type

application/json

{"success": true
}

Update multiple invoice statuses

Updates the status of multiple invoices in a single request. The user must have permission to update invoice statuses and be associated with both the provider and organization for each invoice.

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Default: false Filter by cancelled status

Request Body schema: application/json
required

invoiceIds	Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] IDs of the invoices to update. If this parameter is specified, query filters will be ignored.
status required	string Enum: "draft" "sent" "accepted" "paid" "completed" "rejected" "processing" "not_valid" New status for the invoice
invoicePaymentId	string <uuid> ID of the invoice payment (required when status is "completed")
rejectionReason	string non-empty Reason for rejection (required when status is "rejected").

Responses

Request samples

Payload

Content type

application/json

{"invoiceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"status": "draft",
"invoicePaymentId": "6bd8b670-9f7a-4e56-85e1-a4ae4bb96850",
"rejectionReason": "string"
}

Response samples

Content type

application/json

{"status": [{"invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
"status": "draft"
}
]
}

Create invoice payment (upload or stamp mode)

Creates an invoice payment record for previously paid invoices. This endpoint supports two modes:

Upload Mode: When invoicePaymentXml is provided, uploads and processes an existing payment complement XML file. The endpoint validates the uploaded files and creates an invoice payment record.

Stamp Mode: When no invoicePaymentXml or invoicePaymentPdf is provided, automatically stamps a new payment complement (type "P") using the Facturapi API. The payment complement is created based on the specified invoices and their associated payment information.

Common Validations (both modes):

All invoices must exist and be accessible by the user
All invoices must have payment method PPD (Pago en Parcialidades o Diferido)
All invoices must have status PAID
All invoices must belong to the same organization
All invoices must be related to the same Payment object
All invoices from the payment must be included in the request

Authorizations:

OAuth2

query Parameters

invoice_ids

required

string <uuid>

Comma separated list of IDs of the invoices to create payment complement for

Request Body schema:
multipart/form-data
required

invoicePaymentXml	string <binary> XML file with payment complement (complemento de pago). Required for upload mode. If provided, the endpoint will process the uploaded XML file.
invoicePaymentPdf	string <binary> PDF file of the payment receipt. Optional. If not provided in upload mode, a PDF will be generated automatically.

Responses

Request samples

Payload

Content type

multipart/form-data

No sample

Response samples

Content type

application/json

{"success": false,
"invoices": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"series": "string",
"folioNumber": "string",
"grossPriceAmount": 0
}
],
"message": "Some invoices referenced in the invoice payment were not specified in the request"
}

Download invoice payment

Initiates an async download of a zip file containing the XML and PDF (if it exists) of the specified invoice payment. Returns a File object immediately with status processing. The zip is built asynchronously, uploaded to blob storage, and a realtime notification (invoice_payment_download_ready or invoice_payment_download_failed) is sent when done. The user must have access to the invoice payment through a linked invoice (as organization or provider).

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice payment to download

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Credit Notes

List credit notes

Retrieves a paginated list of credit notes. User must belong to either the organization or the provider and have LIST permission on invoices.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization
provider_id required	string <uuid> ID of the provider
uuid	string Filter by credit note UUID
statuses	string Example: statuses=processing,valid,applied,not_valid Comma-separated list of statuses to filter by
created_at_from	string <date-time>
created_at_to	string <date-time>
issued_at_from	string <date-time>
issued_at_to	string <date-time>
stamped_at_from	string <date-time>
stamped_at_to	string <date-time>
issuer_name	string
recipient_name	string
issuer_tax_identifier	string
recipient_tax_identifier	string
page	integer Default: 1
limit	integer Default: 10
sort	string Comma-separated sort fields (e.g. createdAt,issuedAt,grossPriceAmount)
order	string Enum: "asc" "desc" Comma-separated sort orders (asc, desc). Must match sort fields count.

Responses

Response samples

200
400

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "string",
"status": "processing",
"statusCode": 0,
"folioNumber": "string",
"series": "string",
"currencyCode": "string",
"cfdiUse": "string",
"paymentMethod": "string",
"paymentForm": "string",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"recipientName": "string",
"recipientTaxIdentifier": "string",
"issuedAt": "2019-08-24T14:15:22Z",
"stampedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0,
"isCancelled": true,
"type": "string",
"relationType": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
"organization": {"id": "string",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
},
"provider": {"id": "string",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
},
"items": [ ],
"relatedInvoices": [{"invoiceId": "string",
"invoice": {"id": "string",
"uuid": "string",
"folioNumber": "string",
"series": "string"
}
}
]
}
],
"totalCount": 0,
"totalPages": 0
}

Upload a credit note

Uploads a credit note XML (and optional PDF). The credit note must reference existing invoices (CfdiRelacionados). All related invoices must exist, belong to the organization, and be in ACCEPTED or PAID status. When created, related invoices are automatically set to ANNULLED status.

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization (required if not using provider_id)
provider_id	string <uuid> ID of the provider

Request Body schema: multipart/form-data
required

creditNoteXml required	string <binary> XML file containing the CFDI credit note (TipoDeComprobante E)
creditNotePdf	string <binary> Optional PDF version of the credit note

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"creditNote": { },
"message": "string"
}

Get credit note detail

Retrieves a single credit note by ID or UUID. User must belong to the organization or provider.

Authorizations:

OAuth2

path Parameters

id

required

string

Credit note ID or UUID

Responses

Response samples

200

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "string",
"status": "processing",
"statusCode": 0,
"folioNumber": "string",
"series": "string",
"currencyCode": "string",
"cfdiUse": "string",
"paymentMethod": "string",
"paymentForm": "string",
"issuerName": "string",
"issuerTaxIdentifier": "string",
"recipientName": "string",
"recipientTaxIdentifier": "string",
"issuedAt": "2019-08-24T14:15:22Z",
"stampedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0,
"isCancelled": true,
"type": "string",
"relationType": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",
"organization": {"id": "string",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
},
"provider": {"id": "string",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string"
},
"items": [{"id": "string",
"description": "string",
"quantity": 0,
"unitKey": "string",
"itemKey": "string",
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0,
"taxes": [ ]
}
],
"relatedInvoices": [{"invoiceId": "string",
"invoice": {"id": "string",
"uuid": "string",
"folioNumber": "string",
"series": "string"
}
}
],
"taxes": [ ],
"xmlFile": {"id": "string",
"downloadUrl": "string",
"filename": "string"
},
"pdfFile": {"id": "string",
"downloadUrl": "string",
"filename": "string"
},
"validationErrors": "string"
}

Apply credit note to invoice

Applies a credit note to an invoice. Reduces the invoice's grossPriceAmount by the credit note amount and sets the credit note status to APPLIED. Constraints:

Invoice must be in a non-paid status (not PAID, not COMPLETED)
Invoice must have category 'sat'
Invoice grossPriceAmount must be >= credit note grossPriceAmount
Credit note must be in VALID status

Authorizations:

OAuth2

path Parameters

invoiceId

required

string

Invoice ID

Request Body schema: application/json
required

creditNoteId

required

string

Credit note ID to apply

Responses

Request samples

Payload

Content type

application/json

{"creditNoteId": "string"
}

Response samples

200
400

Content type

application/json

{"success": true,
"invoice": {"id": "string"
},
"creditNote": {"id": "string"
}
}

Invoice Items

Create invoice item

Creates a new invoice item for an existing invoice. Can only be created if the invoice status is 'sent' or 'accepted' and category is not 'sat'.

Authorizations:

OAuth2

Request Body schema: application/json
required

invoiceId required	string <uuid> ID of the invoice to create the item for
description required	string non-empty Description of the invoice item
quantity required	integer >= 1 Quantity of the invoice item
netPriceAmount	number >= 0 Net price amount for the invoice item (in MXN). Either this or `originalNetPriceAmount` must be provided.
originalNetPriceAmount	number >= 0 Net price amount in the original currency. Can only be specified for invoices with category 'foreign' and a non-MXN `originalCurrencyCode`. Either this or `netPriceAmount` must be provided.
discount	number >= 0 Default: 0 Discount amount for the invoice item
chartId	string or null <uuid> ID of the chart to assign to the invoice item as receivable invoice. Can only be set by users belonging to the provider organization. The chart must belong to the provider organization and cannot be a parent chart. When provided, chartMode is automatically set to 'manual'. Set to null to explicitly not assign a chart.
chartAsPayableId	string or null <uuid> ID of the chart to assign to the invoice item as payable invoice. Can only be set by users belonging to the organization. The chart must belong to the organization and cannot be a parent chart. When provided, chartAsPayableMode is automatically set to 'manual'. Set to null to explicitly not assign a chart.

Responses

Request samples

Payload

Content type

application/json

{"invoiceId": "123e4567-e89b-12d3-a456-426614174000",
"description": "Product description",
"quantity": 5,
"netPriceAmount": 1000.5,
"originalNetPriceAmount": 50,
"discount": 0,
"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"chartAsPayableId": "e5cbc150-426d-4c07-8f16-2678e9338d6e"
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
"description": "string",
"quantity": 0,
"netUnitPriceAmount": 0,
"netPriceAmount": 0,
"grossPriceAmount": 0,
"discount": 0
}
}

Update invoice item

Updates a invoice item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice item to update

Request Body schema: application/json
required

chartId	string or null <uuid> ID of the chart to assign to the invoice item as receivable invoice. When updating chartId, the chartMode is automatically set: if the previous chartMode was 'reasoning', it will be set to 'reinforcement'; otherwise, it will be set to 'manual'. Set to null to remove the chart assignment.
chartAsPayableId	string or null <uuid> ID of the chart to assign to the invoice item as payable invoice. When updating chartAsPayableId, the chartAsPayableMode is automatically set: if the previous chartAsPayableMode was 'reasoning', it will be set to 'reinforcement'; otherwise, it will be set to 'manual'. Set to null to remove the chart assignment.
netPriceAmount	number >= 0 Net price amount for the invoice item (in MXN). Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status). When updated, automatically recalculates netUnitPriceAmount, grossPriceAmount, item taxes, invoice taxes, and invoice totals.
originalNetPriceAmount	number >= 0 Net price amount in the original currency. Can only be specified for invoices with category 'foreign' and a non-MXN `originalCurrencyCode`. Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status).
quantity	integer >= 1 Quantity for the invoice item. Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status). When updated, automatically recalculates netUnitPriceAmount, grossPriceAmount, item taxes, invoice taxes, and invoice totals.
description	string non-empty Description of the invoice item. Must be at least 1 character long if provided. Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED', otherwise it will return a 400 error (invalid_payment_method or invalid_status).
chartReasoningConfirmed	boolean Used to mark when a human has confirmed the chart reasoning for the receivable chart.
chartAsPayableReasoningConfirmed	boolean Used to mark when a human has confirmed the chart reasoning for the payable chart.

Responses

Request samples

Payload

Content type

application/json

{"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"chartAsPayableId": "e5cbc150-426d-4c07-8f16-2678e9338d6e",
"netPriceAmount": 1000.5,
"originalNetPriceAmount": 50,
"quantity": 5,
"description": "Product description",
"chartReasoningConfirmed": true,
"chartAsPayableReasoningConfirmed": true
}

Response samples

Content type

application/json

{"success": true,
"message": "Invoice item updated successfully"
}

Delete invoice item

Deletes an invoice item. Can only be deleted if the invoice status is 'sent' or 'accepted', category is not 'sat', and the invoice has more than one item (cannot delete the last item).

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice item to delete

Responses

Response samples

Content type

application/json

{"success": true
}

Create invoice item tax

Creates a new tax for an invoice item. Can only be created if the invoice category is not 'sat' and status is 'ACCEPTED'. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:

OAuth2

Request Body schema: application/json
required

invoiceItemId required	string <uuid> ID of the invoice item to add the tax to
taxId required	string <uuid> ID of the tax. Must be a valid tax ID.
rate required	number >= 0 Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the item's netPriceAmount.

Responses

Request samples

Payload

Content type

application/json

{"invoiceItemId": "123e4567-e89b-12d3-a456-426614174000",
"taxId": "123e4567-e89b-12d3-a456-426614174001",
"rate": 0.16
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoiceItemId": "f67649b2-10bf-48d7-88da-9e916e62d319",
"taxId": "ec2f3321-4009-45bd-9423-63aa80044823",
"code": "string",
"isWithholding": true,
"baseAmount": 0,
"rate": 0,
"value": 0
}
}

Update invoice item tax

Updates an invoice item tax. Can only be updated if the invoice category is not 'sat' and status is 'ACCEPTED'. When rate is updated, automatically recalculates baseAmount and value. When taxId is updated, automatically populates code and isWithholding. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice item tax to update

Request Body schema: application/json
required

taxId	string <uuid> ID of the tax. Must be a valid tax ID.
rate	number >= 0 Tax rate (e.g., 0.16 for 16%). Used to calculate the tax value based on the item's netPriceAmount.

Responses

Request samples

Payload

Content type

application/json

{"taxId": "123e4567-e89b-12d3-a456-426614174001",
"rate": 0.16
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"invoiceItemId": "f67649b2-10bf-48d7-88da-9e916e62d319",
"taxId": "ec2f3321-4009-45bd-9423-63aa80044823",
"code": "string",
"isWithholding": true,
"baseAmount": 0,
"rate": 0,
"value": 0
}
}

Delete invoice item tax

Deletes an invoice item tax. Can only be deleted if the invoice category is not 'sat' and status is 'ACCEPTED'. Automatically recalculates item grossPriceAmount, invoice totals, and invoice-level taxes.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the invoice item tax to delete

Responses

Response samples

Content type

application/json

{"success": true
}

Balance

Get balance

Get balance of the organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization to fetch balance for

Responses

Response samples

200
400
401
403

Content type

application/json

{"balanceAmount": 0,
"lastTransactionAt": "2019-08-24T14:15:22Z"
}

Add balance to organization

Adds balance to an organization. The amount must be at least the minimum balance amount. Requires an organization to have a verified status. If no payment method is specified, the default payment method will be used.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to add balance to
amount required	number <decimal> Amount to add (in MXN). Minimum balance amount required.
payment_method_id	string <uuid> ID of the payment method to use. If not provided, the default payment method will be used.

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Bank Accounts

List Bank Accounts

Retrieves a list of bank accounts for a specific organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID to filter bank accounts

Responses

Response samples

200
400
401
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"organizationsOnOrganizations": [{"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"avatarUrl": "string",
"name": "string",
"commercialName": "string"
}
}
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Create a bank account

Creates a new bank account for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID to create the bank account for

Request Body schema: application/json
required

description required	string Bank account description
bankIdentifier required	string Bank identifier
beneficiaryName required	string Beneficiary name
contactFirstName required	string Contact first name
contactLastName required	string Contact last name
contactEmailAddress required	string Contact email address
contactPhoneNumber required	string Contact phone number
contactJobTitle required	string Contact job title
isDefault	boolean Default: false Whether the bank account is the default bank account

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"bankIdentifier": "string",
"beneficiaryName": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"contactJobTitle": "string",
"isDefault": false
}

Response samples

200
400
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get Bank Account

Retrieves a specific bank account by ID

Authorizations:

OAuth2

path Parameters

id

required

string

Bank account ID

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"organizationsOnOrganizations": [{"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"avatarUrl": "string",
"name": "string",
"commercialName": "string"
}
}
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update Bank Account

Updates an existing bank account

Authorizations:

OAuth2

path Parameters

id

required

string

Bank account ID

Request Body schema: application/json
required

description required	string Bank account description
bankIdentifier required	string Bank identifier
beneficiaryName required	string Beneficiary name
contactFirstName required	string Contact first name
contactLastName required	string Contact last name
contactEmailAddress required	string Contact email address
contactPhoneNumber required	string Contact phone number
contactJobTitle required	string Contact job title
isDefault	boolean Default: false Whether the bank account is the default bank account

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"bankIdentifier": "string",
"beneficiaryName": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"contactJobTitle": "string",
"isDefault": false
}

Response samples

200
400
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"bankId": "string",
"bankIdentifier": "string",
"contactFirstName": "string",
"contactLastName": "string",
"contactEmailAddress": "string",
"contactPhoneNumber": "string",
"beneficiaryName": "string",
"isDefault": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete Bank Account

Deletes a specific bank account

Authorizations:

OAuth2

path Parameters

id

required

string

Bank account ID

Responses

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Payment Cards

List payment cards

Retrieves payment cards for an organization. Requires organization_id. Last 4 digits are unique per organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400
401
403

Content type

application/json

[{"id": "string",
"organizationId": "string",
"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Create payment card

Creates a payment card for an organization. Last 4 digits must be unique within the organization; returns 400 (payment_card_last4_exists) if a card with the same last4 already exists.

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Request Body schema: application/json
required

description required	string non-empty
type required	string Enum: "debit" "credit" "prepaid"
brand required	string Enum: "VISA" "Mastercard" "AMEX"
last4 required	string = 4 characters ^[0-9]{4}$
notes	string or null
cardManagerName required	string non-empty

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string"
}

Response samples

201
400

Content type

application/json

{"id": "string",
"organizationId": "string",
"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get payment card

Retrieves a payment card by ID.

Authorizations:

OAuth2

path Parameters

id

required

string

Payment card ID

Responses

Response samples

200

Content type

application/json

{"id": "string",
"organizationId": "string",
"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update payment card

Updates a payment card. All body fields optional. Returns 400 (payment_card_last4_exists) if last4 is changed to a value already used by another card in the organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payment card ID

Request Body schema: application/json

description	string non-empty
type	string Enum: "debit" "credit" "prepaid"
brand	string Enum: "VISA" "Mastercard" "AMEX"
last4	string = 4 characters ^[0-9]{4}$
notes	string or null
cardManagerName	string non-empty

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string"
}

Response samples

200
400

Content type

application/json

{"id": "string",
"organizationId": "string",
"description": "string",
"type": "debit",
"brand": "VISA",
"last4": "stri",
"notes": "string",
"cardManagerName": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete payment card

Deletes a payment card by ID.

Authorizations:

OAuth2

path Parameters

id

required

string

Payment card ID

Responses

Response samples

200

Content type

application/json

{"success": true
}

Organization Cash

Get organization cash balance

Retrieves the organization cash balance (separate from billing balance). Returns balanceAmount 0 if no record exists.

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400

Content type

application/json

{"organizationId": "string",
"balanceAmount": 0,
"updatedAt": "2019-08-24T14:15:22Z"
}

Top-up organization cash

Adds amount to the organization cash balance. Creates an OrganizationCash record if none exists; otherwise increments balanceAmount. Each top-up is recorded as an OrganizationCashTransaction (transactionType top_up).

Authorizations:

OAuth2

query Parameters

organization_id

string

Organization ID (can also be sent in body as organization_id)

Request Body schema: application/json
required

amount required	number > 0 Positive amount to add
organization_id	string Organization ID (optional if provided in query)

Responses

Request samples

Payload

Content type

application/json

{"amount": 0,
"organization_id": "string"
}

Response samples

200
400

Content type

application/json

{"organizationId": "string",
"balanceAmount": 0,
"updatedAt": "2019-08-24T14:15:22Z"
}

Expenses

Get expenses list

Retrieves a paginated list of expenses with optional filters

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
issuer_tax_identifier	string Filter by issuer tax identifier
issuer_name	string Filter by issuer name
sort	string Default: "createdAt" Enum: "priceAmount" "createdAt" "issuedAt" Field to sort by
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 30 Enum: 10 30 60 100 Number of items per page
minimun_price_amount	number Example: minimun_price_amount=1000 Filter by minimum price amount
maximun_price_amount	number Example: maximun_price_amount=2000 Filter by maximum price amount
payment_form	string Example: payment_form=02,03 Filter by payment form, comma separated
item_description	string Example: item_description=item description Filter by item description
archived	string Default: "false" Enum: "true" "false" Filter by archive status. When "true", returns only archived expenses; when "false" (default), returns only non-archived expenses.

Responses

Response samples

200
400
401
402

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"taxIdentifier": "string",
"commercialName": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"createdAt": "2024-12-01T17:24:59.146Z",
"updatedAt": "2024-12-01T17:24:59.146Z",
"issuedAt": "2024-12-01T17:24:59.146Z",
"priceAmount": 0,
"readAt": "2019-08-24T14:15:22Z",
"archivedAt": "2019-08-24T14:15:22Z",
"items": [{"description": "Factura por pagar",
"quantity": 1,
"priceAmount": 1000,
"discount": 100
}
],
"issuerTaxIdentifier": "string",
"issuerName": "string",
"paymentForm": "string",
"paymentFormDescription": "string",
"isDemo": true,
"isDuplicateOf": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"folioNumber": "string",
"barCodeNumber": "string",
"issuedAt": "2019-08-24T14:15:22Z",
"priceAmount": 0
},
"isVerbatim": true,
"confidenceScore": 0,
"classification": "receipt",
"isPending": false,
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}
}
],
"totalPages": 0,
"totalCount": 0,
"amount": 0,
"unreadCount": 0,
"duplicatesCount": 0,
"itemCount": 0,
"itemsWithChartCount": 0
}

Create a new expense

Creates a new expense by uploading a PDF or image file

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization the expense is for
force_fail	boolean Force failure analysis of the expense image. If the value is 'true', an empty expense will be created and a failure notification will be sent to the organization.

Request Body schema: multipart/form-data
required

expensePdf

required

string <binary>

PDF version of the expense

Responses

Response samples

200
400

Content type

application/json

{"success": true,
"message": "File uploaded successfully"
}

Delete multiple expenses

Deletes multiple expenses in a single request. Requires an array of expense IDs in the request body.

Authorizations:

OAuth2

query Parameters

organization_id

string <uuid>

ID of the organization to delete expenses for. Only required when 'duplicates' in request body is true.

Request Body schema: application/json
required

expenseIds	Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] Array of expense IDs to delete
duplicates	boolean Whether to delete duplicates

Responses

Request samples

Payload

Content type

application/json

{"expenseIds": ["550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001"
],
"duplicates": true
}

Response samples

Content type

application/json

{"success": true
}

Update expenses

Updates a list of expenses

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
issuer_tax_identifier	string Filter by issuer tax identifier
issuer_name	string Filter by issuer name
sort	string Default: "createdAt" Enum: "priceAmount" "createdAt" "issuedAt" Field to sort by
order	string Default: "desc" Enum: "asc" "desc" Sort order
minimun_price_amount	number Example: minimun_price_amount=1000 Filter by minimum price amount
maximun_price_amount	number Example: maximun_price_amount=2000 Filter by maximum price amount
payment_form	string Example: payment_form=02,03 Filter by payment form, comma separated
item_description	string Example: item_description=item description Filter by item description

Request Body schema: application/json
required

expenseIds	Array of strings <uuid> <= 100 items [ items <uuid > ] IDs of the epxenses to update. If this parameter is specified, query filters will be ignored.
isRead	boolean Mark expenses as read (true) or unread (false). Use this for bulk read/unread updates; do not send together with archive.
archive	boolean Archive (true) or unarchive (false) the given expenses. When true, expenses are archived; when false, they are restored from archive. Do not send together with isRead.

Responses

Request samples

Payload

Content type

application/json

{"expenseIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"isRead": true,
"archive": true
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Get expenses balance

Retrieves the balance of expenses for an organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
issuer_tax_identifier	string Filter by issuer tax identifier
issuer_name	string Filter by issuer name
minimun_price_amount	number Example: minimun_price_amount=1000 Filter by minimum price amount
maximun_price_amount	number Example: maximun_price_amount=2000 Filter by maximum price amount
payment_form	string Example: payment_form=02,03 Filter by payment form, comma separated
item_description	string Example: item_description=item description Filter by item description

Responses

Response samples

200
400
401
402

Content type

application/json

{"priceAmount": 1000
}

Download expenses as a zip or xls file

Downloads a zip or xls file containing all selected expenses

Authorizations:

OAuth2

query Parameters

format required	string Enum: "zip" "xls" Format of the file to download
expense_ids required	string Comma separated list of IDs of the expenses to download. If this parameter is specified, all other query filters (except 'format') will be ignored.
organization_id	string <uuid> ID of the organization to fetch invoices for
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
issuer_tax_identifier	string Filter by issuer tax identifier
issuer_name	string Filter by issuer name
sort	string Default: "createdAt" Enum: "priceAmount" "createdAt" "issuedAt" Field to sort by
order	string Default: "desc" Enum: "asc" "desc" Sort order
minimun_price_amount	number Example: minimun_price_amount=1000 Filter by minimum price amount
maximun_price_amount	number Example: maximun_price_amount=2000 Filter by maximum price amount
payment_form	string Example: payment_form=02,03 Filter by payment form, comma separated
item_description	string Example: item_description=item description Filter by item description

Responses

Response samples

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"type": "string",
"filename": "string",
"url": "string",
"status": "processing"
}

Upload expenses as a zip file

Uploads a zip file containing expenses

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Request Body schema: multipart/form-data
required

expensesUploadZipId

string <uuid>

Responses

Response samples

Content type

application/json

{"success": true,
"message": "File uploaded successfully"
}

Get expense details by ID

Retrieves detailed information about a specific expense

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the expense to retrieve

Responses

Response samples

200
401
402
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"folioNumber": "string",
"barCodeNumber": "string",
"priceAmount": 0,
"pdfFile": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"pathname": "string",
"contentType": "application/pdf",
"contentDisposition": "string",
"downloadUrl": "http://example.com",
"type": "expense",
"filename": "string",
"url": "http://example.com"
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"issuedAt": "2019-08-24T14:15:22Z",
"organization": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"commercialName": "string",
"taxIdentifier": "string",
"taxRegimes": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string"
}
],
"isEntity": true,
"isDemoMode": true,
"postalCode": "string",
"status": "pending",
"facturapiValidationErrors": "string",
"bankId": "string",
"bankIdentifier": "string"
},
"items": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"quantity": 0,
"priceAmount": 0,
"unitPriceAmount": 0,
"discount": 0,
"chart": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"description": "string"
},
"isVerbatim": true
}
],
"issuerTaxIdentifier": "string",
"issuerName": "string",
"addressCity": "string",
"addressState": "string",
"isDemo": true,
"isDuplicateOf": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"folioNumber": "string",
"barCodeNumber": "string",
"issuedAt": "2019-08-24T14:15:22Z",
"priceAmount": 0
},
"notes": "string",
"confidenceScore": 0,
"confidenceScoreDescription": "string",
"paymentForm": "string",
"paymentFormDescription": "string",
"isVerbatim": true,
"ratings": [{"rating": "positive"
}
],
"classification": "receipt",
"isPending": false,
"annotations": "string"
}

Update expense

Updates an expense

path Parameters

id

required

string <uuid>

ID of the expense to update

Request Body schema: application/json
required

folioNumber	string
barCodeNumber	string
issuedAt	string <date-time>
issuerName	string
issuerTaxIdentifier	string
addressCity	string
addressState	string
notes	string
paymentForm	string Payment form code of the expense
priceAmount	number <decimal> Price amount of the expense
isRead	boolean
isDuplicateOf	string or null 'null' is the only valid value.
annotations	string or null User-defined annotations for the expense

Responses

Request samples

Payload

Content type

application/json

{"folioNumber": "1234567890",
"barCodeNumber": "09876543211234567890",
"issuedAt": "2019-08-24T14:15:22Z",
"issuerName": "Establecimiento",
"issuerTaxIdentifier": "RFC12345678XA",
"addressCity": "Ciudad de México",
"addressState": "México",
"notes": "Notas de la factura",
"paymentForm": "string",
"priceAmount": 0,
"isRead": true,
"isDuplicateOf": "string",
"annotations": "string"
}

Response samples

Content type

application/json

{"success": true
}

Delete expense

Deletes an expense. The request body must include a non-empty deleteReason.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the expense to delete

Request Body schema: application/json
required

deleteReason

required

string non-empty

Reason for deleting the expense. Stored with the expense snapshot in DeletedItem for audit.

Responses

Request samples

Payload

Content type

application/json

{"deleteReason": "Expense was created by mistake"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Rate the expense

Rates the expense details generated by the AI

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the expense to rate

Request Body schema: application/json
required

rating

string

Enum: "positive" "negative" "neutral"

User rating of the expense details generated by the AI

Responses

Request samples

Payload

Content type

application/json

{"rating": "positive"
}

Response samples

Content type

application/json

{"success": true
}

Expense Items

Create a new expense item

Creates a new expense item

Request Body schema: application/json
required

expenseId	string <uuid> ID of the expense to create the item for
description	string Description of the expense item
quantity	number <decimal> Quantity of the expense item
unitPriceAmount	number <decimal> Unit price amount of the expense item
priceAmount	number <decimal> Price amount of the expense item
discount	number <decimal> Discount amount of the expense item
chartId	string <uuid> ID of the chart to assign to the expense item

Responses

Request samples

Payload

Content type

application/json

{"expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc",
"description": "string",
"quantity": 0,
"unitPriceAmount": 0,
"priceAmount": 0,
"discount": 0,
"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d"
}

Response samples

Content type

application/json

{"success": true,
"data": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc",
"description": "string",
"quantity": 0,
"priceAmount": 0,
"discount": 0,
"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",
"updatedById": "d8bc6076-4141-4a88-80b9-0eb31643066f"
}
}

Update expense item

Updates a expense item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the expense item to update

Request Body schema: application/json
required

description	string Description of the expense item
quantity	number <decimal> Quantity of the expense item
priceAmount	number <decimal> Price amount of the expense item
discount	number <decimal> Discount amount of the expense item
chartId	string or null <uuid> ID of the chart to assign to the expense item.
chartReasoningConfirmed	boolean Used to mark when a human has confirmed the chart reasoning.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"quantity": 0,
"priceAmount": 0,
"discount": 0,
"chartId": "54f93a91-b046-4439-9ec5-17949db5a60d",
"chartReasoningConfirmed": true
}

Response samples

Content type

application/json

{"success": true,
"message": "Expense item updated successfully"
}

Delete expense item

Deletes a expense item

path Parameters

id

required

string <uuid>

ID of the expense item to delete

Responses

Response samples

Content type

application/json

{"success": true
}

Items

List items

Lists all items

Authorizations:

OAuth2

query Parameters

organization_id

required

any

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"itemKey": "string",
"unitKey": "string",
"unitDescription": "string",
"netUnitPriceAmount": 0
}
]

Create item

Creates an item

Request Body schema: application/json
required

description	string Description of the item
itemKey	string Item key
unitKey	string Unit key
netUnitPriceAmount	number <decimal> Unit price

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"itemKey": "string",
"unitKey": "string",
"netUnitPriceAmount": 0
}

Response samples

200
400
401
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"itemKey": "string",
"unitKey": "string",
"unitDescription": "string",
"netUnitPriceAmount": 0
}

Get item

Gets an item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the item to get

Responses

Response samples

200
400
401
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"itemKey": "string",
"unitKey": "string",
"unitDescription": "string",
"netUnitPriceAmount": 0
}

Update item

Updates an item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the item to update

Request Body schema: application/json
required

description	string Description of the item
itemKey	string Item key
unitKey	string Unit key
netUnitPriceAmount	number <decimal> Unit price

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"itemKey": "string",
"unitKey": "string",
"netUnitPriceAmount": 0
}

Response samples

200
400
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"itemKey": "string",
"unitKey": "string",
"unitDescription": "string",
"netUnitPriceAmount": 0
}

Delete item

Deletes an item

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the item to delete

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Payments

Create a payment

Creates a payment for an invoice. When creating a payment by requesting the CEP, the following information is required:

Either paymentTrackingNumber or paymentReferenceNumber must be provided
Bank information for both issuer and recipient is required
Payment date (paidAt) must be provided in ISO 8601 format (YYYY-MM-DD) and cannot be in the future

When creating a payment by adding a payment proof file, a payment proof file must be attached

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to fetch invoices for
provider_id	string <uuid> ID of the provider to fetch invoices for
uuid	string <uuid> Filter by invoice UUID
folio_number	string Example: folio_number=1234567890 Filter by invoice folio number
series	string Example: series=S Filter by invoice series
statuses	string Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
created_at_from	string <date-time> Filter deductibles created after this date
created_at_to	string <date-time> Filter deductibles created before this date
issued_at_from	string <date-time> Filter deductibles issued after this date
issued_at_to	string <date-time> Filter deductibles issued before this date
stamped_at_from	string <date-time> Filter deductibles stamped after this date
stamped_at_to	string <date-time> Filter deductibles stamped before this date
payment_due_at_from	string <date-time> Filter invoices payment due after this date
payment_due_at_to	string <date-time> Filter invoices payment due before this date
sent_at_from	string <date-time> Filter invoices sent after this date
sent_at_to	string <date-time> Filter invoices sent before this date
created_at_period	string Example: created_at_period=2025-01 Filter invoices created in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_period	string Example: issued_at_period=2025-01 Filter invoices issued in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_period	string Example: stamped_at_period=2025-01 Filter invoices stamped in this period. Format: YYYY-MM. If a date range filter is provided, the service returns a HTTP 400 error.
created_at_current_period	boolean Default: false Filter invoices created in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
issued_at_current_period	boolean Default: false Filter invoices issued in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
stamped_at_current_period	boolean Default: false Filter invoices stamped in the current period. If a date range filter is provided, the service returns a HTTP 400 error.
archived	boolean Default: false Filter by archived status
issuer_name	string Example: issuer_name=test Filter by issuer name
recipient_name	string Example: recipient_name=test Filter by recipient name
issuer_tax_identifier	string Example: issuer_tax_identifier=1234567890 Filter by issuer tax identifier
recipient_tax_identifier	string Example: recipient_tax_identifier=1234567890 Filter by recipient tax identifier
issuer_is_entity	boolean Default: false Filter by issuer entity status
recipient_is_entity	boolean Default: false Filter by recipient entity status
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD Filter by payment method
payment_form	string Example: payment_form=99 Filter by payment form
tax_ids	string Example: tax_ids=cma92gmsa0000ji041o9vcovz,cma92gmsa0000ji041o9vcovz Filter by tax ids, comma separated
tax_rates	string Example: tax_rates=0.16 Filter by tax rates, comma separated. If provided, must be the same length as tax_ids.
cfdi_uses	string Example: cfdi_uses=G03,G04 Filter by cfdi uses, comma separated
minimun_gross_price_amount	number Example: minimun_gross_price_amount=1000 Filter by minimum gross price amount
maximun_gross_price_amount	number Example: maximun_gross_price_amount=2000 Filter by maximum gross price amount
item_key	string Example: item_key=50202310 Filter by item key
item_description	string Example: item_description=item description Filter by item description
category	string Enum: "sat" "foreign" "government" "pament_notice" Filter by invoice category
is_cancelled	boolean Default: false Filter by cancelled status

Request Body schema: application/json
required

invoiceIds	Array of strings <uuid> [ items <uuid > ]
paymentProofFileId	string <uuid> ID of the payment proof file (only when status is "paid", optional)
paymentTrackingNumber	string Payment tracking number (either this or paymentReferenceNumber is required when status is "paid")
paymentReferenceNumber	string Payment reference number (either this or paymentTrackingNumber is required when status is "paid")
paymentIssuerBankId	string Bank code of the issuing bank (required when status is "paid")
paymentRecipientBankIdentifier	string = 18 characters CLABE of the receiving bank account (required when status is "paid")
paymentIsOrderingBank	boolean Whether this is an ordering bank payment (required when status is "paid")
paidAt	string <date> Date when the payment was made, in Mexico timezone (required when status is "paid", must be in YYYY-MM-DD format and not in the future)

Responses

Request samples

Payload

Content type

application/json

{"invoiceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"paymentProofFileId": "1c3bfd57-07b6-4dab-8d12-b28ae346ad5e",
"paymentTrackingNumber": "string",
"paymentReferenceNumber": "string",
"paymentIssuerBankId": "012",
"paymentRecipientBankIdentifier": "012180001234567890",
"paymentIsOrderingBank": true,
"paidAt": "2024-03-20"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Update a payment's paidAt

Updates the paidAt (and optionally paidAtUpdateReason) of a payment by ID. Only these fields can be updated. The user must belong to the invoice's organization and have permission to update payments according to their role. The payment must not be rolled back. paidAt must be a valid ISO 8601 date or datetime and cannot be in the future.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the payment to update

Request Body schema: application/json
required

paidAt required	string When the payment was made. ISO 8601 date (YYYY-MM-DD) or datetime (e.g. YYYY-MM-DDTHH:mm:ssZ). Cannot be in the future.
paidAtUpdateReason	string Enum: "manual" "payment_proof" "payment_proof_reason" Reason for updating the paidAt value (InvoiceFieldUpdateReason). Optional.

Responses

Request samples

Payload

Content type

application/json

{"paidAt": "2025-01-20T14:30:00Z",
"paidAtUpdateReason": "manual"
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true
}

Delete a payment.

Deletes a payment. All invoices associated with the payment will rollback to status 'accepted'. All invoices associated with the payment must be in 'paid' status, otherwise the service will return HTTP 400 with error 'invalid_invoice_status'

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the payment to delete

query Parameters

force

boolean

Default: false

Whether to force delete the payment

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"invoices": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
"commercialName": "string",
"grossPriceAmount": 0
}
]
}

Payroll

Reason payroll payment proof

Starts AI analysis of the payroll payment proof file associated with the given payroll payment. Accepts payrollPaymentId. The endpoint returns immediately with the created PayrollPaymentProof id (status processing). Analysis runs in the background; on completion a real-time notification is emitted (payroll_payment_proof_created or payroll_payment_proof_failed).

Authorizations:

OAuth2

Request Body schema: application/json
required

payrollPaymentId

required

string

ID of the payroll payment whose proof file will be analyzed

Responses

Request samples

Payload

Content type

application/json

{"payrollPaymentId": "string"
}

Response samples

Content type

application/json

{"success": true,
"payrollPaymentProof": {"id": "string"
}
}

Get payroll payment proof by ID

Returns the PayrollPaymentProof entity with status, source fields used for comparison, extracted fields and confidence scores from the AI analysis. User must have DETAIL access to payroll for the proof's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll payment proof ID

Responses

Response samples

200
404

Content type

application/json

{"id": "string",
"payrollPaymentId": "string",
"status": "processing",
"sourceIssuerName": "string",
"sourcePaidAt": "2019-08-24T14:15:22Z",
"sourceEmployeesCount": 0,
"sourceAmount": 0,
"issuerName": "string",
"paidAt": "2019-08-24T14:15:22Z",
"employeesCount": 0,
"amount": 0,
"issuerNameConfidenceScore": 0,
"paidAtConfidenceScore": 0,
"employeesCountConfidenceScore": 0,
"amountConfidenceScore": 0,
"tokenCount": 0,
"pdfProcessingPrice": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get payroll configuration

Returns the payroll configuration for an organization (schedule: weekly, biweekly, or monthly). Requires authentication. User must have DETAIL access to the organization's payroll configuration and belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Organization identifier

Responses

Response samples

200
400

Content type

application/json

{"payrollConfiguration": {"id": "string",
"organizationId": "string",
"schedule": "weekly"
}
}

Update payroll configuration

Creates or updates the payroll configuration for an organization (upsert). Requires authentication. User must have UPDATE access to the organization's payroll configuration and belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Organization identifier

Request Body schema: application/json
required

schedule

string or null

Enum: "weekly" "biweekly" "monthly"

Payroll schedule (weekly, biweekly, or monthly).

Responses

Request samples

Payload

Content type

application/json

{"schedule": "weekly"
}

Response samples

200
400

Content type

application/json

{"success": true,
"payrollConfiguration": {"id": "string",
"organizationId": "string",
"schedule": "weekly"
}
}

Get payroll with periods for a month

Returns the payroll for an organization and period (YYYY-MM), including all periods for that month. If no Payroll record exists for the period, the schedule is taken from PayrollConfiguration and periods are computed on-the-fly (existing DB periods are merged with generated ones so the list is always complete). If no periods exist and no schedule is configured, returns 400 payroll_configuration_missing. Requires authentication. User must have DETAIL access to payroll for the organization and belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID
period required	string^\d{4}-\d{2}$ Example: period=2026-02 Period in YYYY-MM format (e.g. 2026-02)

Responses

Response samples

200
400

Content type

application/json

{"payroll": {"organizationId": "string",
"periodDate": "2026-02",
"schedule": "weekly",
"employeesCount": 0,
"payrollPeriodCount": 0,
"payrollPeriodEmployeeAmount": "string",
"periods": [{"id": "string",
"organizationId": "string",
"status": "string",
"periodNumber": 0,
"periodNumberInYear": 0,
"periodStartAt": "2019-08-24",
"periodEndAt": "2019-08-24",
"totalAmount": "string",
"employeesCount": 0,
"obligationsAmount": "string"
}
]
}
}

Upload one or more payroll (nómina) XMLs

Uploads one or more SAT nómina CFDI XMLs (TipoDeComprobante N) for the given organization. Maximum 10 XML files per request; for larger batches use POST /api/payroll/upload-zip. Query params period (YYYY-MM) and period_number are optional. When both provided, they must be valid; when both omitted, period and period_number are derived from each XML's FechaInicialPago using the organization's payroll schedule. They must be both provided or both omitted (returns 400 if only one is sent). Send multiple files using the same multipart field name "file". Each file is validated (TipoComprobante, Emisor RFC vs organization, period dates, SAT status, duplicate) and processed independently; failures are reported per file. Returns successCount, failureCount, and errors (filename + errorCode) like upload-zip. Creates Payroll and PayrollPeriod if needed, then Employee or PayrollPeriodEmployee and related data for each successful XML. Requires authentication. User must have DETAIL access to payroll and belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID
period	string^\d{4}-\d{2}$ Example: period=2026-01 Period in YYYY-MM format (e.g. 2026-01). Optional; when omitted (together with period_number), derived from each XML's FechaInicialPago.
period_number	integer >= 1 Example: period_number=1 Period number within the month (1-based integer). Optional; when omitted (together with period), derived from each XML's FechaInicialPago.

Request Body schema: multipart/form-data
required

file

required

Array of strings <binary> [ items <binary > ]

One or more payroll (nómina) CFDI XML files (same field name for multiple)

Responses

Response samples

200
400

Content type

application/json

{"successCount": 0,
"failureCount": 0,
"errors": [{"filename": "string",
"errorCode": "invoice_type_not_valid"
}
]
}

Upload a ZIP of payroll (nómina) XMLs

Uploads a ZIP file containing one or more SAT nómina CFDI XMLs. Each XML is validated and processed like the single-upload endpoint. Query params period (YYYY-MM) and period_number are optional. When both provided, they must be valid; when both omitted, period and period_number are derived from each XML's FechaInicialPago using the organization's payroll schedule. They must be both provided or both omitted (returns 400 if only one is sent). Returns successCount, failureCount, and a list of errors (filename + errorCode) for each failed file. Does not fail the whole request on single-file errors. Requires authentication. User must have DETAIL access to payroll and belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID
period	string^\d{4}-\d{2}$ Period in YYYY-MM format. Optional; when omitted (together with period_number), derived from each XML's FechaInicialPago.
period_number	integer >= 1 Period number (1-based integer). Optional; when omitted (together with period), derived from each XML's FechaInicialPago.

Request Body schema: multipart/form-data
required

file

required

string <binary>

ZIP file containing .xml files

Responses

Response samples

200
400

Content type

application/json

{"successCount": 0,
"failureCount": 0,
"errors": [{"filename": "string",
"errorCode": "invoice_type_not_valid"
}
]
}

List payroll period employees (paginated)

Returns a paginated list of payroll period employees for a given payroll period. Response includes data, totalCount, totalPages, and pendingCount (number of employees in the period with isPending=true). Each item includes id, name, role, department, amount, and isPending. Requires authentication. User must have DETAIL access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

query Parameters

payroll_period_id required	string Payroll period ID
page	integer >= 1 Default: 1 Page number (1-based). Default 1.
limit	integer Default: 10 Page size (alias pageSize). Default 10.
pageSize	integer Page size (alias for limit).
sort	string Default: "name" Enum: "name" "role" "department" "amount" Sort field. One of name, role, department, amount. Default name.
order	string Default: "asc" Enum: "asc" "desc" Sort order. asc or desc. Default asc.
q	string Search by name or tax identifier (partial match, case-insensitive).
role	string Filter by role (exact match). Multiple comma-separated values (e.g. "Developer,Designer").
department	string Filter by department (exact match). Multiple comma-separated values (e.g. "Engineering,Product").

Responses

Response samples

200
400
404

Content type

application/json

{"data": [{"id": "string",
"name": "string",
"role": "string",
"department": "string",
"amount": "string",
"isPending": true
}
],
"totalCount": 0,
"totalPages": 0,
"pendingCount": 0
}

Get payroll period employee detail

Returns detail for a single payroll period employee by ID (employeeId, name, role, department, daysPaid, payrollPeriod dates, perceptions, deductions, amount). Requires authentication. User must have DETAIL access to payroll for the employee's period organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period employee ID

Responses

Response samples

200
400
404

Content type

application/json

{"employeeId": "string",
"name": "string",
"role": "string",
"department": "string",
"daysPaid": 0,
"amount": "string",
"isPending": true,
"payrollPeriod": {"periodStartAt": "2019-08-24",
"periodEndAt": "2019-08-24"
},
"perceptions": [{"description": "string",
"taxableAmount": "string",
"exemptAmount": "string"
}
],
"deductions": [{"description": "string",
"amount": "string"
}
]
}

List unique departments for payroll period employees

Returns a unique list of department values from payroll period employees for the given payroll period ID, sorted alphabetically by department name. Requires authentication. User must have DETAIL access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period ID

Responses

Response samples

200
400
404

Content type

application/json

{"departments": ["string"
]
}

List unique roles for payroll period employees

Returns a unique list of role values from payroll period employees for the given payroll period ID, sorted alphabetically by role name. Requires authentication. User must have DETAIL access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period ID

Responses

Response samples

200
400
404

Content type

application/json

{"roles": ["string"
]
}

Get payroll period with perceptions, deductions, and obligations

Returns a single payroll period by ID with its global perceptions, deductions, and obligations. No pagination. Requires authentication. User must have DETAIL access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period ID

Responses

Response samples

200
400
404

Content type

application/json

{"payrollPeriod": {"id": "string",
"payrollId": "string",
"organizationId": "string",
"schedule": "weekly",
"status": "string",
"periodNumber": 0,
"periodStartAt": "2019-08-24",
"periodEndAt": "2019-08-24",
"totalAmount": "string",
"perceptionsAmount": "string",
"deductionsAmount": "string",
"obligationsAmount": "string",
"payrollPeriodEmployeesCount": 0,
"reportPdfFile": {"id": "string",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"filename": "string",
"type": "string"
},
"payrollPayment": {"id": "string",
"paidAt": "2019-08-24T14:15:22Z",
"payrollPaymentProofFile": {"id": "string",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"filename": "string",
"type": "string"
},
"payrollPaymentProof": {"id": "string",
"status": "processing",
"pdfProcessingPrice": "string"
}
},
"perceptions": [{"id": "string",
"description": "string",
"chartId": "string",
"chartMode": "string",
"chartConfidenceScore": "string",
"taxableAmount": "string",
"exemptAmount": "string"
}
],
"deductions": [{"id": "string",
"description": "string",
"chartId": "string",
"chartMode": "string",
"chartConfidenceScore": "string",
"amount": "string"
}
],
"obligations": [{"id": "string",
"key": "string",
"description": "string",
"chartId": "string",
"chartMode": "string",
"chartConfidenceScore": "string",
"amount": "string"
}
],
"payrollReport": {"id": "string",
"status": "string",
"reportPdfFile": {"id": "string",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"filename": "string",
"type": "string"
}
}
}
}

Upload payroll report PDF for period

Uploads a payroll report PDF for the period. Creates a PayrollReport (status processing) and runs AI analysis in the background. When analysis finishes, the report status becomes pending (missing employees), applied (no missing employees), or error. Returns 400 if no payroll period employees (XMLs) have been uploaded for this period. Returns 402 if any PayrollPeriodEmployee has isPending status. Returns 400 if a report is already processing, pending, or applied for this period. Requires authentication. User must have EDIT access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period ID

Request Body schema: multipart/form-data
required

file

required

string <binary>

Payroll report PDF file

Responses

Response samples

201
400
402
404
500

Content type

application/json

{"success": true,
"payrollReportId": "string"
}

Remove report PDF file from payroll period

Removes the report PDF file for the payroll period (sets reportPdfFileId to null), deletes all obligations for the period, and sets obligationsAmount to null. Only allowed when the period status is not "paid". Requires authentication. User must have EDIT access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period ID

Responses

Response samples

200
400
404
500

Content type

application/json

{"success": true
}

Get payroll report status

Returns the status of a payroll report by ID. Status is one of processing, pending, applied, or error. Requires authentication. User must have DETAIL access to payroll for the report's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll report ID

Responses

Response samples

200
400
404

Content type

application/json

{"status": "processing"
}

Update payroll report status to applied

Updates the payroll report status. The only allowed transition is pending -> applied. Request body must include status "applied". If the report is not in pending status, returns 400. Only status=applied is accepted in the body. Requires authentication. User must have EDIT access to payroll for the report's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll report ID

Request Body schema: application/json
required

status

required

string

Value: "applied"

Only "applied" is accepted

Responses

Request samples

Payload

Content type

application/json

{"status": "applied"
}

Response samples

200
400
404

Content type

application/json

{"status": "applied"
}

Register payroll period payment

Registers a payment for a payroll period using a previously uploaded payment proof file. The file must have been uploaded with type PAYROLL_PAYMENT_PROOF. Creates a PayrollPayment and sets the period status to paid. Payroll period must be in status "pending"; otherwise returns 400. Only one payment per period is allowed. Requires authentication. User must have EDIT access to payroll for the period's organization and belong to that organization.

Authorizations:

OAuth2

Request Body schema: application/json
required

payrollPeriodId required	string Payroll period ID
payrollPaymentProofFileId required	string ID of the previously uploaded payment proof file (type PAYROLL_PAYMENT_PROOF)

Responses

Request samples

Payload

Content type

application/json

{"payrollPeriodId": "string",
"payrollPaymentProofFileId": "string"
}

Response samples

201
400
404
500

Content type

application/json

{"success": true,
"payrollPayment": {"id": "string",
"payrollPeriodId": "string",
"payrollPaymentProofFileId": "string",
"paidAt": "2019-08-24T14:15:22Z",
"paidAtUpdateReason": "manual",
"createdAt": "2019-08-24T14:15:22Z"
}
}

Delete payroll payment

Deletes a payroll payment by ID. The associated PayrollPaymentProof (if any) is removed by cascade. The payroll period status is reverted from "paid" to "created". Requires authentication. User must have EDIT access to payroll for the payment's organization and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll payment ID

Responses

Response samples

404

Content type

application/json

{"error": "payroll_payment_not_found"
}

Update payroll period perception chart

Updates the chartId for a payroll period perception (global perception line). Same logic as expense item PATCH chartId; chart must belong to the period's organization and must not be a parent chart. When setting a chart, chartMode is set to reinforcement if the previous mode was reasoning, otherwise manual; when clearing (chartId null), chartMode is set to manual.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period perception ID

Request Body schema: application/json
required

chartId

string or null

Chart ID to assign, or null to clear.

Responses

Request samples

Payload

Content type

application/json

{"chartId": "string"
}

Response samples

200
400
404
500

Content type

application/json

{"success": true
}

Update payroll period deduction chart

Updates the chartId for a payroll period deduction (global deduction line). Same logic as expense item PATCH chartId; chart must belong to the period's organization and must not be a parent chart. When setting a chart, chartMode is set to reinforcement if the previous mode was reasoning, otherwise manual; when clearing (chartId null), chartMode is set to manual.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period deduction ID

Request Body schema: application/json
required

chartId

string or null

Chart ID to assign, or null to clear.

Responses

Request samples

Payload

Content type

application/json

{"chartId": "string"
}

Response samples

200
400
404
500

Content type

application/json

{"success": true
}

Update payroll period obligation chart

Updates the chartId for a payroll period obligation (global obligation line). Same logic as expense item PATCH chartId; chart must belong to the period's organization and must not be a parent chart. When setting a chart, chartMode is set to reinforcement if the previous mode was reasoning, otherwise manual; when clearing (chartId null), chartMode is set to manual.

Authorizations:

OAuth2

path Parameters

id

required

string

Payroll period obligation ID

Request Body schema: application/json
required

chartId

string or null

Chart ID to assign, or null to clear.

Responses

Request samples

Payload

Content type

application/json

{"chartId": "string"
}

Response samples

200
400
404
500

Content type

application/json

{"success": true
}

Employees

List employees for organization

Returns paginated list of employees for the given organization_id. Each item has id, name, role, department, payrollPeriodEmployeesCount (number of payroll period records for that employee), totalAmount (sum of amount across all periods for that employee). Response includes totalCount (total employees), totalAmount (sum of amount across all payroll period employees in the org), totalPayrollPeriodEmployeesCount, totalPages. Sort by name (default asc), payrollPeriodEmployeesCount, role, department, totalAmount. Requires authentication. User must have DETAIL access to payroll for the organization and belong to that organization.

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID
page	integer >= 1 Default: 1
limit	integer Default: 10 Page size (alias pageSize)
pageSize	integer
sort	string Default: "name" Enum: "name" "payrollPeriodEmployeesCount" "role" "department" "totalAmount" Sort field. One of name, payrollPeriodEmployeesCount, role, department, totalAmount. Default name.
order	string Default: "asc" Enum: "asc" "desc"
q	string Search/filter by text (matches against employee name, role, department, or similar)
role	string Example: role=Developer,Designer Filter by role(s). Comma-separated list; employee role must match one of the values.
department	string Example: department=Engineering,Product Filter by department(s). Comma-separated list; employee department must match one of the values.

Responses

Response samples

200
400

Content type

application/json

{"totalCount": 0,
"totalAmount": "string",
"totalPayrollPeriodEmployeesCount": 0,
"totalPages": 0,
"data": [{"id": "string",
"name": "string",
"role": "string",
"department": "string",
"payrollPeriodEmployeesCount": 0,
"totalAmount": "string"
}
]
}

List unique departments for employees

Returns all unique department values for employees in the organization, sorted alphabetically. Requires authentication. User must have DETAIL access to payroll for the organization and belong to that organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400

Content type

application/json

{"data": ["string"
]
}

List unique roles for employees

Returns all unique role values for employees in the organization, sorted alphabetically. Requires authentication. User must have DETAIL access to payroll for the organization and belong to that organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID

Responses

Response samples

200
400

Content type

application/json

{"data": ["string"
]
}

Get employee detail

Returns employee detail by ID (id, taxIdentifier, identificationNumber, socialSecurityNumber, employmentStartAt, contractPdfFile). Requires authentication. User must have DETAIL access to payroll for an organization that has this employee in at least one payroll period, and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Employee ID

Responses

Response samples

200
400
404

Content type

application/json

{"id": "string",
"taxIdentifier": "string",
"identificationNumber": "string",
"socialSecurityNumber": "string",
"employmentStartAt": "2019-08-24",
"contractPdfFile": {"id": "string",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"filename": "string",
"type": "string"
}
}

Upload employee contract PDF

Uploads and sets the contract PDF file for the employee. Request body must be multipart/form-data with a field "contractPdf" (file). Accepts application/pdf or application/x-pdf. Requires authentication. User must have EDIT access to payroll for an organization that has this employee in at least one payroll period, and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Employee ID

Request Body schema: multipart/form-data
required

contractPdf

required

string <binary>

Contract PDF file

Responses

Response samples

200
400
404
500

Content type

application/json

{"success": true
}

Remove contract PDF from employee

Removes the contract PDF from the employee Returns 404 if the employee has no contract PDF. Requires authentication. User must have EDIT access to payroll for an organization that has this employee, and belong to that organization.

Authorizations:

OAuth2

path Parameters

id

required

string

Employee ID

Responses

Response samples

200
400
404

Content type

application/json

{"success": true
}

List payroll history for employee

Returns paginated list of payroll period employees for the given employee (payroll history). Each item has payrollPeriod (periodStartAt, periodEndAt, status), amount, and xmlFile. Sorted by periodStartAt descending by default. Sortable by amount, payrollPeriod.periodStartAt, payrollPeriod.status. Requires authentication. User must have DETAIL access to payroll for an organization that has this employee in at least one payroll period.

Authorizations:

OAuth2

path Parameters

id

required

string

Employee ID

query Parameters

page	integer >= 1 Default: 1
limit	integer Default: 10 Page size (alias pageSize)
pageSize	integer
sort	string Default: "payrollPeriod.periodStartAt" Enum: "amount" "payrollPeriod.periodStartAt" "payrollPeriod.status" Sort field. One of amount, payrollPeriod.periodStartAt, payrollPeriod.status. Default payrollPeriod.periodStartAt.
order	string Default: "desc" Enum: "asc" "desc"

Responses

Response samples

200
400
404

Content type

application/json

{"data": [{"payrollPeriod": {"periodStartAt": "2019-08-24",
"periodEndAt": "2019-08-24",
"status": "string"
},
"amount": "string",
"xmlFile": {"id": "string",
"pathname": "string",
"contentType": "string",
"contentDisposition": "string",
"downloadUrl": "string",
"filename": "string",
"type": "string"
}
}
],
"totalCount": 0,
"totalPages": 0
}

Taxes

Get taxes

Returns a list of taxes. By default, returns only global taxes (organization_id = null). If organization_id is provided, returns taxes for that organization plus global taxes. If invoice_category is provided, filters taxes to only those that support the specified category (taxes with null invoiceCategories are included as they support all categories). Requires authentication and user must belong to the organization if organization_id is specified.

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> Organization ID to filter taxes. If provided, returns organization-specific taxes plus global taxes.
invoice_category	string Example: invoice_category=expense Filter taxes by invoice category. Returns only taxes that support this category (taxes with null invoiceCategories support all categories).

Responses

Response samples

200
401
403

Content type

application/json

[{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"name": "string",
"description": "string",
"isWithholding": true
}
]

Create a tax for an organization

Creates a new tax for a specific organization. Requires authentication and user must belong to the organization.

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

Organization ID to create the tax for

Request Body schema: application/json
required

name required	string Tax name
description required	string Tax description
code	string Tax code
isWithholding	boolean Default: false Whether this is a withholding tax
invoiceCategories	Array of strings List of invoice categories that this tax supports or is intended for. If not provided or null, the tax supports all categories.

Responses

Request samples

Payload

Content type

application/json

{"name": "IVA",
"description": "Impuesto al Valor Agregado",
"code": "002",
"isWithholding": false,
"invoiceCategories": ["sat",
"foreign",
"government"
]
}

Response samples

201
400
401
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"code": "string",
"name": "string",
"description": "string",
"isWithholding": true,
"organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Payment Proofs

Create a payment proof

Creates a payment proof by analyzing a payment proof file and associating it with one or more invoices. The payment proof file will be processed asynchronously using AI to extract payment information. All invoices must be in 'paid' status, belong to the same organization and provider (if applicable), and must not already be associated with another payment proof. The maximum number of invoices per payment proof is 100.

Authorizations:

OAuth2

Request Body schema: application/json
required

paymentProofFileId required	string <uuid> ID of the payment proof file to analyze
invoiceIds required	Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ] Array of invoice IDs to associate with this payment proof. All invoices must be in 'paid' status, belong to the same organization and provider, and must not already be associated with another payment proof.

Responses

Request samples

Payload

Content type

application/json

{"paymentProofFileId": "1c3bfd57-07b6-4dab-8d12-b28ae346ad5e",
"invoiceIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}

Response samples

200
400
401
403
404

Content type

application/json

{"success": true,
"paymentProof": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}

Get payment proof details by ID

Retrieves detailed information about a specific payment proof

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

ID of the payment proof to retrieve

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"issuerBankIdentifier": "string",
"recipientBankIdentifier": "string",
"issuerName": "string",
"beneficiaryName": "string",
"paidAt": "2019-08-24",
"description": "string",
"grossPriceAmount": 0,
"issuerBankIdentifierConfidenceScore": 0,
"recipientBankIdentifierConfidenceScore": 0,
"beneficiaryNameConfidenceScore": 0,
"descriptionConfidenceScore": 0,
"grossPriceAmountConfidenceScore": 0,
"paidAtConfidenceScore": 0,
"referenceNumberConfidenceScore": 0,
"status": "processing",
"sourcePaidAt": "string",
"sourceIssuerBankIdentifier": "string",
"sourceRecipientBankIdentifier": "string",
"sourceIssuerName": "string",
"sourceBeneficiaryName": "string",
"sourceDescription": "string",
"sourceGrossPriceAmount": 0,
"sourceOriginalGrossPriceAmount": 0,
"sourceReferenceNumber": "string",
"pdfProcessingPrice": 0,
"paidInOriginalCurrency": true
}

Dashboard

Get income and outcome stats

Retrieves income and outcome stats for the organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to filter statistics for
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD,PUE Comma-separated list of payment methods to filter by
payment_form	any Payment form code to filter by
issuer_name	any Issuer name to filter by
recipient_name	any Recipient name to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)

Responses

Response samples

200
400
401
403

Content type

application/json

{"totalIncomeGrossPriceAmount": 0,
"invoicesReceivableTotalGrossPriceAmountNotGeneric": null,
"invoicesReceivableTotalGrossPriceAmountGeneric": null,
"invoicesReceivableTotalGrossPriceAmountGenericForeign": null,
"totalOutcomeGrossPriceAmount": 0,
"invoicesPayableTotalGrossPriceAmount": 0,
"deductiblesTotalGrossPriceAmount": 0,
"expensesTotalPriceAmount": 0,
"payrollPaidTotalGrossPriceAmount": 0
}

Get top employees by payroll amount

Retrieves top employees by amount paid from paid payroll periods whose period (periodStartAt to periodEndAt) falls within or overlaps the requested date range.

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to filter statistics for
date_from required	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to required	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
employee_name	string Filter employees by name (partial match, case-insensitive)
include_totals	boolean Default: false When true, includes totalGrossPriceAmount and totalEmployeesCount in the response
order	string Default: "desc" Enum: "asc" "desc" Sort order for top employees by amount
page	integer Default: 1 Page number for pagination
limit	integer Default: 5 Maximum number of employees to return per page

Responses

Response samples

200
400

Content type

application/json

{"topEmployees": [{"name": "string",
"amount": 0
}
],
"totalGrossPriceAmount": 0,
"totalEmployeesCount": 0,
"totalPages": 0
}

Get top organizations for invoices

Retrieves top organizations from invoices for the organization

Authorizations:

OAuth2

query Parameters

provider_id	string <uuid> ID of the provider to filter statistics for
organization_id	string <uuid> ID of the organization to filter statistics for
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD,PUE Comma-separated list of payment methods to filter by
payment_form	any Payment form code to filter by
statuses	string Default: "paid,completed" Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
issuer_name	any Issuer name to filter by
recipient_name	any Recipient name to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
payment_due_at_from	string <date> Example: payment_due_at_from=2024-01-01 Start payment due date for the statistics period (ISO 8601 format)
payment_due_at_to	string <date> Example: payment_due_at_to=2024-01-31 End payment due date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"grossPriceAmount": 0,
"invoiceCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top items for invoices

Retrieves top items from invoices for the organization

Authorizations:

OAuth2

query Parameters

provider_id	string <uuid> ID of the provider to filter statistics for
organization_id	string <uuid> ID of the organization to filter statistics for
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD,PUE Comma-separated list of payment methods to filter by
payment_form	any Payment form code to filter by
statuses	string Default: "paid,completed" Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
description	any Item description to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
payment_due_at_from	string <date> Example: payment_due_at_from=2024-01-01 Start payment due date for the statistics period (ISO 8601 format)
payment_due_at_to	string <date> Example: payment_due_at_to=2024-01-31 End payment due date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"grossPriceAmount": 0,
"quantity": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalQuantity": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top payment forms for invoices

Retrieves top payment forms from invoices for the organization

Authorizations:

OAuth2

query Parameters

provider_id	string <uuid> ID of the provider to filter statistics for
organization_id	string <uuid> ID of the organization to filter statistics for
payment_method	string Enum: "PPD" "PUE" Example: payment_method=PPD,PUE Comma-separated list of payment methods to filter by
payment_form	any Payment form code to filter by
statuses	string Default: "paid,completed" Example: statuses=draft,sent,accepted,paid,completed,rejected,processing,not_valid,annulled Comma-separated list of invoice statuses to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
payment_due_at_from	string <date> Example: payment_due_at_from=2024-01-01 Start payment due date for the statistics period (ISO 8601 format)
payment_due_at_to	string <date> Example: payment_due_at_to=2024-01-31 End payment due date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"paymentForm": "string",
"grossPriceAmount": 0,
"invoiceCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top organizations for deductibles

Retrieves top organizations from deductibles for the organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
issuer_name	any Issuer name to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"grossPriceAmount": 0,
"invoiceCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top items for deductibles

Retrieves top items from deductibles for the organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
description	any Item description to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"grossPriceAmount": 0,
"quantity": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalQuantity": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top payment forms for deductibles

Retrieves top payment forms from deductibles for the organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
date_from	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"paymentForm": "string",
"grossPriceAmount": 0,
"invoiceCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalGrossPriceAmount": 0,
"totalInvoicesCount": 0
}

Get top organizations for expenses

Retrieves top organizations from expenses for the organization

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
issuer_name	any Issuer name to filter by
date_from required	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to required	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"priceAmount": 0,
"expenseCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalPriceAmount": 0,
"totalExpensesCount": 0
}

Get top items for expenses

Retrieves top items from expenses for the organization

Authorizations:

OAuth2

query Parameters

organization_id	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
description	any Item description to filter by
date_from required	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to required	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"name": "string",
"priceAmount": 0,
"quantity": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalQuantity": 0,
"totalPriceAmount": 0,
"totalExpensesCount": 0
}

Get top payment forms for expenses

Retrieves top payment forms from expenses for the organization

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to filter statistics for
payment_form	any Payment form code to filter by
date_from required	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to required	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)
order	string Default: "desc" Enum: "asc" "desc" Sort order
page	integer >= 1 Default: 1 Page number for pagination
limit	integer Default: 5 Enum: 5 10 30 60 100 Number of items per page
include_totals	any Whether to include summarized values and page count in the response

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"paymentForm": "string",
"priceAmount": 0,
"expenseCount": 0
}
],
"totalCount": 0,
"totalPages": 0,
"totalPriceAmount": 0,
"totalExpensesCount": 0
}

Get invoice preferences requirements for an organization

Retrieves invoice preferences requirements for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"status": "verified",
"isBankingInformationRequired": true,
"isComplianceDocumentRequired": true
}

Get charts with amounts

Retrieves charts with amounts for the organization

Authorizations:

OAuth2

query Parameters

organization_id required	string <uuid> ID of the organization to filter statistics for
parent_code	any Example: parent_code=109-02-001 Parent code to filter by
date_from required	string <date> Example: date_from=2024-01-01 Start date for the statistics period (ISO 8601 format)
date_to required	string <date> Example: date_to=2024-01-31 End date for the statistics period (ISO 8601 format)

Responses

Response samples

200
400
401
403

Content type

application/json

[{"code": "string",
"description": "string",
"totalAmount": 0,
"itemCount": 0,
"childrenCount": 0
}
]

Get dashboard alerts for an organization

Retrieves dashboard alerts for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string <uuid>

ID of the organization

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"pastDuePayableInvoicesCount": 0,
"pastDueReceivableInvoicesCount": 0,
"sentPayableInvoicesCount": 0,
"createdExpensesCount": 0,
"createdDeductiblesCount": 0,
"paidReceivableInvoicesCount": 0,
"completedPayableInvoicesCount": 0,
"createdProvidersCount": 0
}

Channels

List Channels

Retrieves a paginated list of channels for a specific organization

Authorizations:

OAuth2

query Parameters

organization_id required	string Organization ID to filter channels
page	integer Default: 1 Page number for pagination
limit	integer Default: 30 Number of items per page
sort	string Default: "createdAt" Enum: "description" "whatsappNumber" "createdAt" Field to sort by
order	string Default: "asc" Enum: "asc" "desc" Sort order

Responses

Response samples

200
400
401
403

Content type

application/json

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"whatsappNumber": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"totalPages": 0,
"totalCount": 0
}

Create channel

Creates a new channel for an organization

Authorizations:

OAuth2

query Parameters

organization_id

required

string

Organization ID to create the channel for

Request Body schema: application/json
required

description required	string Channel description
whatsappNumber required	string WhatsApp phone number

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"whatsappNumber": "1234567890"
}

Response samples

200
400
401
403

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"whatsappNumber": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get Channel

Retrieves a specific channel by ID

Authorizations:

OAuth2

path Parameters

id

required

string

Channel ID

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"whatsappNumber": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update Channel

Updates an existing channel

Authorizations:

OAuth2

path Parameters

id

required

string

Channel ID

Request Body schema: application/json
required

description required	string Channel description
whatsappNumber required	string WhatsApp phone number (without + prefix)

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"whatsappNumber": "1234567890"
}

Response samples

200
400
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"description": "string",
"whatsappNumber": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete Channel

Deletes a specific channel

Authorizations:

OAuth2

path Parameters

id

required

string

Channel ID

Responses

Response samples

200
401
403
404

Content type

application/json

{"success": true
}

Tatem (1.0.0)

Authentication

Obtain OAuth2 Token (Resource Owner Password Credentials Grant)

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

Refresh Access Token

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

Logout user

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

Request password reset

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Reset password

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Users

Get user information

Authorizations:

Responses

Response samples

Create a new user

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update user information

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete user

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update user default organization

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Verify whatsapp number

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Verify email address

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Sends the email address verification email

Authorizations:

Responses

Response samples

Send WhatsApp verification code

Authorizations:

Responses

Response samples

Create invitation code

Authorizations:

Responses

Response samples

Organizations

Get organizations list

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required

Request Body schema: multipart/form-data
required