---
title: "Convenciones de API"
description: "Reglas compartidas del contrato REST: versión, JSON, montos, headers, paginación y compatibilidad."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.pagofast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenciones de API

# Convenciones de API

## Base URL, ambientes y versión

La URL base depende del ambiente y debe ser provista por PagoFast. Todas las rutas públicas versionadas comienzan con `/v1`:

```http
GET {base_url}/v1/payment-methods
```

Los recursos de `test` y `live` están aislados. Una API key `sk_test_...` no puede acceder a métodos `live`, y una key `sk_live_...` no puede acceder a métodos `test`.

## Headers comunes

| Header                           | Dirección | Uso                                                                                          |
| -------------------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Authorization: Bearer <token>`  | Request   | JWT de usuario o API key (`sk_test_...` / `sk_live_...`).                                     |
| `Content-Type: application/json` | Request   | Obligatorio cuando hay body JSON.                                                            |
| `Idempotency-Key`                | Request   | Obligatorio en escrituras de negocio documentadas como idempotentes.                         |
| `X-Request-Id`                   | Request   | Opcional; si no se envía, la API lo genera.                                                  |
| `X-Request-Id`                   | Response  | Identificador de correlación (eco del request o generado). Aparece también en `error.request_id`. |

No registres el valor completo de `Authorization` ni otros secretos.

## JSON y nombres

Todos los campos públicos usan `snake_case`. Los clientes deben ignorar campos opcionales desconocidos para tolerar extensiones compatibles.

```json
{
  "external_reference": "order-9821",
  "created_at": "2026-07-17T13:00:00.000Z"
}
```

## Fechas

Las fechas se expresan en ISO 8601 y UTC:

```text
2026-07-17T13:00:00.000Z
```

## Montos y monedas

Los montos son strings decimales para evitar errores binarios de punto flotante. La moneda usa un código ISO 4217.

```json
{
  "amount": {
"value": "12500.00",
"currency": "ARS"
  }
}
```

No envíes números JSON (`12500.00`), separadores de miles (`"12.500,00"`) ni símbolos (`"$12500"`). La cantidad de decimales admitida depende de la moneda y del contrato del endpoint.

## Respuestas exitosas

Un recurso individual se devuelve bajo `data`:

```json
{
  "data": {
"id": "019f704f-89d7-7e83-b3e1-f07c33801024"
  }
}
```

Un listado agrega `pagination` con offset:

```json
{
  "data": [],
  "pagination": {
"limit": 50,
"offset": 0,
"total": 128
  }
}
```

Usá `limit` y `offset` para paginar. `total` indica cuántos ítems coinciden con el filtro.

## Errores

Los errores usan un envelope diferente:

```json
{
  "error": {
"code": "invalid_request",
"message": "La solicitud no cumple el contrato.",
"category": "validation",
"retryable": false,
"request_id": "req_019f704f89d77e83",
"details": {}
  }
}
```

Tomá decisiones programáticas con `code` y `retryable`, no analizando `message`. Conservá `request_id` para soporte. Consultá el [catálogo de errores](/errors).

## Idempotencia

Las escrituras de negocio indicadas en su referencia requieren `Idempotency-Key`. La falta del header devuelve `400 idempotency_key_required`. Una repetición con el mismo body recupera la respuesta guardada; reutilizar la clave con otro body devuelve `409 idempotency_key_reused`.

Consultá [Idempotencia](/idempotency) para elegir claves y reintentar correctamente.

## Compatibilidad

- Agregar campos opcionales es compatible.
- Los clientes deben tolerar campos desconocidos.
- Eliminar campos, volver obligatorio un campo opcional o cambiar su semántica requiere una nueva versión.
- No implementes `switch` exhaustivos sobre enums sin una rama segura para valores futuros.
- Los cambios relevantes se anuncian en el [changelog](/changelog).

## Recomendación para soporte

Al reportar una falla incluí ambiente, endpoint, fecha UTC, `X-Request-Id`, `external_reference` e ID del recurso. No compartas API keys, JWT, credenciales del procesador ni cuerpos con datos sensibles.

Source: https://docs.pagofast.com/api-conventions/index.mdx