Referencia de la API de Makatea

Generada del OpenAPI de producción (versión 2026-09-23). URL base: https://makatea.ai/api. Las descripciones de rutas y campos vienen del spec, en inglés. Las guías en español están en https://makatea.ai/desarrolladores.

Introducción

The Makatea API lets your system create members and billing orders, register payments, and receive events. Every response carries Makatea-API-Version: 2026-09-23 and an X-Request-Id (send your own to correlate logs).

Authentication

Create an API key in Makatea → Settings → API. Send it in either header:

Authorization: Bearer mk_live_…
X-API-Key: mk_live_…

Keys have scopes: read (GET) and write (everything else). A session JWT from the Makatea app is also accepted in Authorization (legacy). Missing or invalid credentials → 401; a key without the needed scope → 403 insufficient_scope.

Responses

Success always has the same shape, for single objects and for lists:

{"data": {…} }
{"data": [ … ], "pagination": {"limit": 100, "has_more": true, "next_cursor": "eyJm…"}}

Errors always look like this:

{"error": {"code": "validation_error", "message": "amount must be a positive number", "request_id": "…"}}

Pagination and sync

Lists accept limit (default 100, max 500) and cursor. Pass the next_cursor you received to get the next page, keeping the same filters; stop when has_more is false. offset still works for compatibility but can skip rows while data changes. Add count=true to get pagination.total (slower).

To mirror data into your system, call the list with updated_since=<last sync instant>: results come ordered by updated_at ascending, so you can page with the cursor and store the updated_at of the last row as your next checkpoint.

Idempotency

Send Idempotency-Key: <unique string> on any POST/PUT/PATCH/DELETE. Retrying with the same key and the same body returns the original response (with header Idempotent-Replayed: true) instead of acting twice. The same key with a different body is 422 idempotency_key_reused; while the first request is still running, 409 idempotency_in_progress. Keys are kept 24 hours.

Webhooks

Register an https endpoint (POST /v1/webhook-endpoints) with the event types you want (or *). The response includes the signing secret (whsec_…) only once. Each event is POSTed as:

{"id": "<event id>", "type": "payment.received", "created_at": "…", "data": {…}}

with headers Makatea-Event-Id, Makatea-Event-Type and

Makatea-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

Verify by recomputing the HMAC over t + "." + raw body and comparing in constant time; reject timestamps older than 5 minutes. Answer 2xx within 10 seconds. Otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after 8 failed attempts the delivery is failed (you can retry it with POST /v1/webhook-deliveries/{id}/retry). Deliveries can arrive more than once or out of order: use the event id to de-duplicate.

Event types: member.created, member.updated, billing_order.created, billing_order.updated, billing_order.paid, billing_order.cancelled, payment.received, payment.voided, promise.created, promise.kept, promise.broken, message.sent, message.received. *.updated events carry {"object": {…}, "previous_attributes": {…}}. Records created by CSV imports do not emit events.

Limits

600 requests per minute per API key (per organization for session JWTs). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds). Over the limit → 429 with Retry-After. Request bodies up to 21 MB; documents up to 15 MB.

Status

GET /v1/status (no key) says whether the service and its database answer.

Índice de rutas

• Status
  • GET /v1/status
• Members
  • GET /v1/members
  • POST /v1/members
  • GET /v1/members/{id}
  • PUT /v1/members/{id}
  • PATCH /v1/members/{id}
  • DELETE /v1/members/{id}
• Promises
  • GET /v1/members/{id}/promises
  • POST /v1/members/{id}/promises
  • DELETE /v1/members/{id}/promises/current
• Credit
  • GET /v1/members/{id}/credit
  • POST /v1/members/{id}/credit/apply
• Messages
  • GET /v1/members/{id}/conversation
  • POST /v1/messages
  • POST /v1/conversations/import
• Documents
  • GET /v1/members/{id}/documents
  • POST /v1/members/{id}/documents
  • DELETE /v1/members/{id}/documents/{document_id}
• Billing orders
  • GET /v1/billing-orders
  • POST /v1/billing-orders
  • GET /v1/billing-orders/{id}
  • PATCH /v1/billing-orders/{id}
  • DELETE /v1/billing-orders/{id}
  • POST /v1/billing-orders/{id}/forgive
  • POST /v1/billing-orders/{id}/late-fees
  • POST /v1/billing-orders/{id}/payment-link
• Payments
  • POST /v1/billing-orders/{id}/pay
  • POST /v1/billing-orders/{id}/payments
  • GET /v1/payments
  • GET /v1/payments/{id}
  • POST /v1/payments/{id}/void
• Credits (loans)
  • GET /v1/credits
  • POST /v1/credits
  • GET /v1/credits/{id}
  • PATCH /v1/credits/{id}
  • GET /v1/settings/payment-allocation
  • PUT /v1/settings/payment-allocation
• Webhooks
  • GET /v1/webhook-endpoints
  • POST /v1/webhook-endpoints
  • DELETE /v1/webhook-endpoints/{id}
  • GET /v1/webhook-events
  • GET /v1/webhook-deliveries
  • POST /v1/webhook-deliveries/{id}/retry
• Operations
  • GET /v1/sequence-runs
  • GET /v1/flows
  • GET /v1/templates
  • GET /v1/stats

Status

GET /v1/status

Service status (no authentication).

Checks that the database answers. Returns 503 when it does not.

Respuestas

• 200 OK · data: Status

Members

GET /v1/members

List members.

Parámetros

Respuestas

• 200 OK · data: array de Member
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

POST /v1/members

Create a member.

Two members may share a phone number. external_ref is unique per organization (409 if reused).

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: Member
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

GET /v1/members/{id}

Get a member (with billing orders and recent interactions).

Parámetros

Respuestas

• 200 OK · data: Member
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

PUT /v1/members/{id}

Update a member.

Only the fields you send are changed.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Member
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

PATCH /v1/members/{id}

Update a member (partial).

Only the fields you send are changed.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Member
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

DELETE /v1/members/{id}

Soft-delete a member (state becomes churned).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Member
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Promises

GET /v1/members/{id}/promises

Current promise and history.

Parámetros

Respuestas

• 200 OK · data: PromiseState
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

POST /v1/members/{id}/promises

Record a payment promise.

Pauses collection messages until the promised date (one reminder survives). Replaces any active promise. When the date passes the promise becomes kept or broken (webhooks promise.kept / promise.broken).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: PromiseState
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

DELETE /v1/members/{id}/promises/current

Cancel the active promise.

Marks it cancelled (kept in history) and re-schedules collection for the member's open orders. 409 if there is no active promise.

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: PromiseState
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Credit

GET /v1/members/{id}/credit

Credit balance and its ledger.

Parámetros

Respuestas

• 200 OK · data: Credit
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

POST /v1/members/{id}/credit/apply

Apply the credit balance to open orders (oldest first).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: CreditApplied
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Messages

GET /v1/members/{id}/conversation

Messages exchanged with a member (newest first).

Parámetros

Respuestas

• 200 OK · data: array de Interaction
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

POST /v1/messages

Send a message to a member.

With text: sent right away through the organization's line (WhatsApp or SMS) — status: sent.

With template_id: queued for the sending engine, which renders the template variables — status: queued (any channel, including email).

Respects opt-outs (409 opted_out), the organization's kill switch (409 comms_disabled) and its send window (409 outside_send_window, text only; queued messages wait for the window).

Organizations in simulation mode record the message but nothing leaves (status: simulated).

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 202 OK · data: MessageResult
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

POST /v1/conversations/import

Import conversation history (messages that happened outside Makatea).

Up to 20,000 rows per call. Idempotent by external_id (or by member + time + direction + text). Imported messages trigger nothing: no auto-replies, no notices, no webhooks. dry_run validates without writing. Members are matched by member_external_ref, or by phone when exactly one member has it.

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de rows:

Respuestas

• 200 OK · data: ConversationImportResult
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

Documents

GET /v1/members/{id}/documents

List a member's documents (with temporary download URLs, valid 1 hour).

Parámetros

Respuestas

• 200 OK · data: array de Document
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

POST /v1/members/{id}/documents

Attach a document to a member.

Send the file inline (content_base64) or a public https url the server downloads. Max 15 MB. With external_ref, repeating the call returns the existing document (200) instead of uploading twice.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: Document
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

DELETE /v1/members/{id}/documents/{document_id}

Delete a document (file and record).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Deleted
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Billing orders

GET /v1/billing-orders

List billing orders.

Default order: due_date ascending. With updated_since: updated_at ascending.

Parámetros

Respuestas

• 200 OK · data: array de BillingOrder
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

POST /v1/billing-orders

Create a billing order.

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

GET /v1/billing-orders/{id}

Get a billing order.

Parámetros

Respuestas

• 200 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

PATCH /v1/billing-orders/{id}

Update a billing order (move the date, change the amount, …).

Moving due_date re-schedules its collection messages. Raising amount above what was paid re-opens a paid order; lowering it to what is covered marks it paid. late_fee sets the accumulated late fee (absolute). capital_portion/interest_portion set the breakdown (also on paid orders: it is history) and re-apply the order's payments. Cancelled orders cannot be edited (409).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

DELETE /v1/billing-orders/{id}

Cancel a billing order (409 if already paid).

Optional reason (query ?reason= or JSON body {"reason": …}, max 500 chars) is stored as cancel_reason — e.g. «consolidated into another account». Cancelling an already cancelled order with a reason updates the reason.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

POST /v1/billing-orders/{id}/forgive

Forgive (condone) part or all of the balance.

Forgiven money is not a payment: it does not appear in /v1/payments. Without amount, forgives the whole balance and the order becomes paid. On orders with a breakdown the forgiveness takes, of what is still owed, late fee first, then interest, then other charges and principal last (forgiven_now_breakdown; forgiven principal is a loss).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

POST /v1/billing-orders/{id}/late-fees

Add a late fee to an order.

Adds to late_fee and fires the late_fee_applied notice if the organization configured one. With collectible: true the fee is also added to amount (it becomes owed; a paid order re-opens). When omitted, the organization's moratorio_cobrable setting decides (default: informational only).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: BillingOrder
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

POST /v1/billing-orders/{id}/payment-link

Create (or reuse) a payment link with the organization's payment provider.

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: PaymentLink
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Payments

POST /v1/billing-orders/{id}/pay

Settle the whole remaining balance.

Registers one payment for exactly the remaining balance. For partial or historical payments use POST /v1/billing-orders/{id}/payments.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: PaymentResult
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

POST /v1/billing-orders/{id}/payments

Register a payment (partial, historical date, overpayment policy).

excess decides what happens when amount is larger than the balance: reject (default) answers 422 amount_exceeds_balance; credit applies the excess to the member's next open orders (oldest first) and keeps the rest as credit balance.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: PaymentResult
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

GET /v1/payments

List payments (the ledger).

Every money movement: payments (kind: payment) and reversals of voided payments (kind: reversal, negative amount). allocation says how each entry was applied to its installment (principal, interest, late fee, other charges, unassigned; null when the installment has no breakdown); a reversal carries exactly the same figures, negative. paid_at is when the money was received (it can be in the past); recorded_at is when the entry reached Makatea — created_since/updated_since and the ordering use recorded_at, so a back-dated payment registered today still shows up in your next sync. The ledger is append-only, so updated_since is an alias of created_since. Default order: newest first; with a *_since filter: oldest first.

Parámetros

Respuestas

• 200 OK · data: array de Payment
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

GET /v1/payments/{id}

Get a payment.

Parámetros

Respuestas

• 200 OK · data: Payment
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

POST /v1/payments/{id}/void

Void a payment.

Writes a reversal (negative) entry, lowers the order's amount_paid and re-opens it if needed. 409 already_voided the second time.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Payment
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

Credits (loans)

GET /v1/credits

List credits (loans) with their principal, what came back and what is owed.

Each credit groups the installments of one loan (external_ref = your folio) and carries its principal. totals are to date: capital_recovered/interest_collected/late_fee_collected = what the payment ledger applied to its installments (voided payments net out); capital_outstanding/interest_outstanding = of its open installments with breakdown; balance = amount − paid − forgiven of its open installments; paid_without_ledger = paid amounts imported as history, with no ledger entry. Default order: start_date descending; with updated_since: updated_at ascending.

Parámetros

Respuestas

• 200 OK · data: array de Loan
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

POST /v1/credits

Create a credit (loan) and attach its installments.

external_ref (your folio) is unique per organization: reusing it is 409. Installments are attached by id or by their external_ref; they must belong to the same member (422 credit_member_mismatch). start_date is when the money was lent: it decides in which period the principal counts as «placed».

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: LoanDetail
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

GET /v1/credits/{id}

Get a credit with its installments and their breakdown.

Parámetros

Respuestas

• 200 OK · data: LoanDetail
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

PATCH /v1/credits/{id}

Update a credit, attach or detach installments.

Only the fields you send change. status can be set to cancelled (the principal stops counting as placed) or back to active; liquidated is computed from its installments.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: LoanDetail
• 401 Missing or invalid credentials
• 404 Not found
• 422 Validation error
• 429 Rate limit exceeded

GET /v1/settings/payment-allocation

How payments are split between late fee, interest and principal.

Respuestas

• 200 OK · data: AllocationRule
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

PUT /v1/settings/payment-allocation

Change the payment allocation rule.

moratorio_interes_capital (default: late fee, then interest, then other charges, then principal), proporcional (each payment split in proportion to what is owed of each part) or al_liquidar (a partial payment stays «unassigned» until the installment is settled; the settling payment recognizes all of its principal and interest on its date). The rule is fixed on each installment when its breakdown is loaded; with apply_existing: true every installment with breakdown is re-applied with the new rule (past figures change).

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: AllocationRule
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

Webhooks

GET /v1/webhook-endpoints

List webhook endpoints.

Respuestas

• 200 OK · data: array de WebhookEndpoint
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

POST /v1/webhook-endpoints

Register a webhook endpoint (the signing secret is returned only here).

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: WebhookEndpointCreated
• 401 Missing or invalid credentials
• 422 Validation error
• 429 Rate limit exceeded

DELETE /v1/webhook-endpoints/{id}

Delete a webhook endpoint (its pending deliveries are dropped).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Deleted
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

GET /v1/webhook-events

List emitted events (newest first).

Events are recorded only while the organization has at least one active endpoint subscribed to that type.

Parámetros

Respuestas

• 200 OK · data: array de WebhookEvent
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

GET /v1/webhook-deliveries

List delivery attempts (newest first).

Parámetros

Respuestas

• 200 OK · data: array de WebhookDelivery
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

POST /v1/webhook-deliveries/{id}/retry

Retry a delivery now (pending or failed).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: WebhookDelivery
• 401 Missing or invalid credentials
• 404 Not found
• 429 Rate limit exceeded

Operations

GET /v1/sequence-runs

List scheduled/sent collection messages (newest scheduled first).

Parámetros

Respuestas

• 200 OK · data: array de SequenceRun
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

GET /v1/flows

List the organization's flows.

Respuestas

• 200 OK · data: array de Flow
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

GET /v1/templates

List the organization's active templates.

Respuestas

• 200 OK · data: array de Template
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

GET /v1/stats

Dashboard numbers — the same figures the app's Panel shows.

Every money figure comes from the same database function the app uses (org_metricas_cobranza), so the API and the Panel never disagree. metrics has the full set for the period (from/to, default: 1st of the current month to today, in the org's timezone): collected = money that came in by payment date (voided payments, credit-balance applications and future-dated rows excluded), overdue/upcoming = real balance (amount − paid − forgiven) of open installments due before / on-or-after today, aging by days late (1-9, 10-30, 31-60, 60+), collection_rate = of what came due in the period up to today, the share already paid. metrics.capital_profit splits the same period into principal and profit: placed (principal lent, by credit start_date), collected.capital|interest|late_fee|other|unassigned|no_breakdown|to_credit_balance (they add up exactly to collected.total, the same «collected» as above), profit = interest + late fee collected with its margin over what was collected with a breakdown, outstanding principal and interest (current / overdue) of open installments, and forgiven split into principal (a loss), interest, late fee and other. coverage.status is none when no installment has a breakdown: then every figure is 0 and no_breakdown carries the money. portfolio and members keep their old shape.

Parámetros

Respuestas

• 200 OK · data: Stats
• 401 Missing or invalid credentials
• 429 Rate limit exceeded

Objetos

Error

Pagination

Status

Member

BillingOrder

Payment

PaymentResult

PromiseState

Credit

CreditApplied

Interaction

MessageResult

ConversationImportResult

Document

Deleted

PaymentLink

object

WebhookEndpoint

WebhookEndpointCreated

object

WebhookEvent

WebhookDelivery

SequenceRun

Flow

Template

Stats

object

Loan

LoanDetail

object

AllocationRule