# Visión general

La **Partner API** de Monetarie es la interfaz servidor a servidor que su sistema usa para crear clientes, abrir y consultar cuentas, enviar PIX y TED, y recibir webhooks. Cada llamada del catálogo está acotada al socio dueño de la credencial: un socio solo ve y mueve las cuentas, los clientes y los webhooks que él mismo creó.

## URL base

La colección y los ejemplos usan la variable `{{baseUrl}}`. Apúntela al endpoint del Core que Monetarie proporciona para su entorno. No use barra al final.

```
{{baseUrl}}/api/partner/v1
```

## Flujo de integración

1. Reciba su `client_id` y `client_secret` (generados en el panel de Monetarie).
2. Intercámbielos por un token de acceso en `POST /api/partner/v1/oauth/token`. Vea [Autenticación](/es/autenticacion).
3. Envíe el token en el encabezado `Authorization: Bearer <access_token>` en todas las demás llamadas.
4. Para operaciones que mueven dinero, envíe un encabezado `Idempotency-Key` para evitar duplicados.
5. Registre [webhooks](/es/endpoints/webhooks) para recibir eventos de forma asíncrona.

## Valores monetarios

- Las entradas de PIX y de transferencias usan **centavos** (número entero). Ejemplo: `1500` representa R$ 15,00.
- Saldo, extracto y comprobante se devuelven en **reales** (número con decimales).

## Idempotencia

Las operaciones de escritura que mueven dinero (crear cliente, enviar PIX, enviar TED y transferencia interna) aceptan el encabezado `Idempotency-Key`. Los reenvíos con la misma clave devuelven la respuesta original.

## Errores

Las respuestas de error siguen un formato consistente, con el código HTTP apropiado:

```json
{
  "error": {
    "status": 403,
    "message": "Permiso insuficiente para esta operación"
  }
}
```

| Código | Significado |
|---|---|
| `400` | Solicitud malformada |
| `401` | Token ausente, inválido o expirado |
| `403` | Alcance insuficiente o recurso de otro socio |
| `404` | Recurso no encontrado |
| `422` | Datos inválidos (validación) |

## Herramientas

- **Postman:** [descargue la colección](/Monetarie-Partner-API.postman_collection.json) y complete `baseUrl`, `client_id` y `client_secret`. La colección se encarga del token y del encabezado `Authorization`.
- **Referencia interactiva:** la especificación del contrato (OpenAPI) está disponible en el entorno del Core que Monetarie proporciona.