# Recursos - [Recursos](#recursos) - [Overview](#overview) - [Moneda](#moneda) - [Frecuencia](#frecuencia) - [Tipo De Descuento](#tipo-de-descuento) - [Tipo de identificación](#tipo-de-identificación) - [Tipo de entrega](#tipo-de-entrega) - [Tipo de checkout](#tipo-de-checkout) - [Frecuencias de expiración en efectivo](#frecuencias-efectivo) - [Estados de una reserva de cupo](#mit-status) - [Códigos de respuesta de reserva de cupo](#mit-response-codes) - [Lista de países](#lista-de-países) - [Lista de departamentos](#lista-de-departamentos) - [Lista de ciudades](#lista-de-ciudades) - [Impuestos](#impuestos) - [Metodos de pago](#metodos-de-pago) - [Lista efectivos](#lista-efectivos) - [Lista bancos pse](#lista-bancos-pse) - [Tipos de identificación pse](#tipos-de-identificación-pse) - [Plantillas de checkout](#checkout-templates) - [Estados de transacciones](#status-transaction) ## Overview [#overview] Los **recursos** son catálogos de solo lectura: las listas de valores válidos que esperan los demás endpoints. Monedas, tipos de documento, países, bancos de PSE, tus impuestos, tus plantillas de checkout. Consúltalos en vez de escribir los valores a mano. Si mañana agregamos un banco a PSE o un tipo de documento, tu integración lo recoge sola. ### Qué es público y qué no Los catálogos que no dependen de tu comercio son **públicos**: no necesitan token. Los que sí dependen de tu configuración piden tu `Authorization`. | Ruta | Auth | Qué devuelve | | - | - | - | | `GET /api/v1/resources/get-countries` | Pública | Países con indicativo e ISO | | `GET /api/v1/resources/get-departments` | Pública | Departamentos con sus ciudades | | `GET /api/v1/resources/get-cities/{department}` | Pública | Ciudades de un departamento | | `GET /api/v1/resources/identification-types-enum` | Pública | Tipos de documento | | `GET /api/v1/resources/currency-enum` | Pública | Monedas | | `GET /api/v1/resources/frequency-enum` | Pública | Frecuencias de recurrencia | | `GET /api/v1/resources/discount-type-enum` | Pública | Tipos de descuento | | `GET /api/v1/resources/checkout-type-enum` | Pública | Tipos de checkout | | `GET /api/v1/resources/cash-frequencies` | Pública | Vencimientos de pago en efectivo | | `GET /api/v1/resources/delivery-service-type-enum` | Pública | Tipos de entrega | | `GET /api/v1/resources/mit/status-enum` | Pública | Estados de una reserva de cupo | | `GET /api/v1/resources/mit/response-codes` | Pública | Códigos de la red, con `retryable` y `action` | | `GET /api/v1/resources/get-status-transaction` | **Token** | Estados de transacción | | `GET /api/v1/resources/get-taxes` | **Token** | Los impuestos configurados en tu comercio | | `GET /api/v1/resources/available-payment-methods` | **Token** | Los métodos habilitados para ti | | `GET /api/v1/resources/checkout/available-cash` | **Token** | Redes de efectivo habilitadas | | `GET /api/v1/resources/checkout/pse-banks` | **Token** | **Bancos de PSE** | | `GET /api/v1/resources/checkout/pse-identification-types` | **Token** | Tipos de documento y de persona para PSE | | `GET /api/v1/resources/get-checkout-templates` | **Token** | Tus plantillas de checkout | :::danger **La lista de bancos de PSE no es pública.** Es el error más común al leer esta página: `checkout/pse-banks` exige `Authorization`, porque depende de la configuración de tu comercio. Si la llamas sin token, recibes `401`. ::: :::caution Todos cuelgan del host de la API (**`https://sag.efipay.co/api/v1`**), el mismo del resto de los endpoints. No los consumas desde el host de QA en producción: no hay garantía de disponibilidad. Ver [Autenticación y ambientes](/authentication#ambientes). ::: ## Moneda [#moneda] ``` GET /api/v1/resources/currency-enum ``` `GET /api/v1/resources/currency-enum` El valor que envías en `currency_type` es el **`abbreviation`**. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "symbol": "$", "abbreviation": "COP", "name": "Peso Colombiano" }, { "symbol": "$", "abbreviation": "USD", "name": "Dolares Estadounidenses" }, { "symbol": "€", "abbreviation": "EUR", "name": "Euro" } ] ``` ## Frecuencia [#frecuencia] ``` GET /api/v1/resources/frequency-enum ``` `GET /api/v1/resources/frequency-enum` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "day", "label": "Day" }, { "value": "week", "label": "Week" }, { "value": "month", "label": "Month" }, { "value": "year", "label": "Year" } ] ``` ## Tipo De Descuento [#tipo-de-descuento] ``` GET /api/v1/resources/discount-type-enum ``` `GET /api/v1/resources/discount-type-enum` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "value", "label": "Value" }, { "value": "percentage", "label": "Percentage" } ] ``` ## Tipo de identificación [#tipo-de-identificación] ``` GET /api/v1/resources/identification-types-enum ``` `GET /api/v1/resources/identification-types-enum` Cada tipo impone su propio formato al número de documento: | Tipo | Formato del número | | - | - | | CC | 6 a 10 dígitos | | CE | alfanumérico, 6 a 15 caracteres | | TI | 10 a 11 dígitos | | PPT | 7 a 15 dígitos | | DNI | alfanumérico, 6 a 20 caracteres | | NIT | 9 a 10 dígitos | | Pasaporte | alfanumérico, 6 a 20 caracteres | | Otro | texto, máximo 30 caracteres | :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "CC", "label": "Cédula de Ciudadanía" }, { "value": "CE", "label": "Cédula de Extranjería" }, { "value": "TI", "label": "Tarjeta de Identidad" }, { "value": "PPT", "label": "Permiso Temporal" }, { "value": "DNI", "label": "DNI" }, { "value": "NIT", "label": "NIT/TAX" }, { "value": "Pasaporte", "label": "Pasaporte" }, { "value": "Otro", "label": "Otro" } ] ``` ## Tipo de entrega [#tipo-de-entrega] ``` GET /api/v1/resources/delivery-service-type-enum ``` `GET /api/v1/resources/delivery-service-type-enum` Ojo: el **valor** que se envía va en español (`Gratis`, `Con Valor`); la etiqueta está en inglés. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "Gratis", "label": "Free" }, { "value": "Con Valor", "label": "With Value" } ] ``` ## Tipo de checkout [#tipo-de-checkout] `redirect` (te damos un link y rediriges) o `api` (capturas el pago en tu propio checkout). Es el valor de `payment.checkout_type` al [generar un pago](/generate-transaction). ``` GET /api/v1/resources/checkout-type-enum ``` `GET /api/v1/resources/checkout-type-enum` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "redirect", "label": "Redirect" }, { "value": "api", "label": "Api" } ] ``` ## Frecuencias de expiración en efectivo [#frecuencias-efectivo] Unidades válidas para `advanced_options.cash_expired_interval`, que define cuánto dura un cupón de pago en efectivo. ``` GET /api/v1/resources/cash-frequencies ``` `GET /api/v1/resources/cash-frequencies` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "minute", "label": "Minute(s)" }, { "value": "hour", "label": "Hour(s)" }, { "value": "day", "label": "Day(s)" }, { "value": "week", "label": "Week(s)" }, { "value": "month", "label": "Month(es)" }, { "value": "year", "label": "Year(s)" } ] ``` ## Estados de una reserva de cupo [#mit-status] Los estados por los que pasa una [reserva de cupo](/mit-pre-authorization), con su etiqueta. ``` GET /api/v1/resources/mit/status-enum ``` `GET /api/v1/resources/mit/status-enum` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "Iniciada", "label": "Esperando al cliente", "color": "warning" }, { "value": "Pre-autorizada", "label": "Cupo reservado", "color": "info" }, { "value": "Confirmada", "label": "Cobrada", "color": "success" }, { "value": "Anulada", "label": "Reserva liberada", "color": "muted" }, { "value": "Vencida", "label": "Reserva vencida", "color": "muted" }, { "value": "Rechazada", "label": "Rechazada", "color": "danger" }, { "value": "Fallida", "label": "Fallida", "color": "danger" }, { "value": "Indeterminada", "label": "Verificando", "color": "warning" } ] ``` ## Códigos de respuesta de reserva de cupo [#mit-response-codes] Catálogo de códigos de la red con su mensaje, la acción sugerida y si tiene sentido reintentar. Consúltalo en vez de escribir los códigos a mano. ``` GET /api/v1/resources/mit/response-codes ``` `GET /api/v1/resources/mit/response-codes` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "code": "00", "message": "Transacción aprobada", "action": "Continúa con el cobro final cuando corresponda.", "retryable": false }, { "code": "51", "message": "Fondos insuficientes", "action": "Pide otro medio de pago a tu cliente.", "retryable": false } ] ``` ## Lista de países [#lista-de-países] ``` GET /api/v1/resources/get-countries ``` `GET /api/v1/resources/get-countries` :::caution Este catálogo devuelve un **objeto indexado por el código ISO2**, no un arreglo. Donde la API te pida un país (`customer_payer.country`, `customer_information.country`) espera el **`iso3_code`**; donde te pida `iso_code` —como al crear una sucursal— espera el de dos letras. ::: :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "CO": { "name": "Colombia", "dialling_code": "+57", "iso_code": "CO", "iso3_code": "COL", "region": "latinAmerica" }, "AD": { "name": "Andorra", "dialling_code": "+376", "iso_code": "AD", "iso3_code": "AND", "region": "europe" } } ``` ## Lista de departamentos [#lista-de-departamentos] ``` GET /api/v1/resources/get-departments ``` `GET /api/v1/resources/get-departments` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "id": 1, "name": "Amazonas" }, { "id": 5, "name": "Antioquia" } ] ``` ## Lista de ciudades [#lista-de-ciudades] ``` GET /api/v1/resources/get-cities/{department} ``` `GET /api/v1/resources/get-cities/{department}` El `{department}` de la ruta es el `id` de la [lista de departamentos](#lista-de-departamentos). :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "id": 1, "name": "Medellín", "department_id": 5 }, { "id": 2, "name": "Envigado", "department_id": 5 } ] ``` ## Impuestos [#impuestos] ``` GET /api/v1/resources/get-taxes ``` `GET /api/v1/resources/get-taxes` En `payment.selected_taxes` envías los **`id`**; en el campo `tax` de un [plan](/plan) envías el **`value`**. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "id": 1, "name": "IVA 19%", "value": 19, "active": true }, { "id": 2, "name": "IVA 5%", "value": 5, "active": true } ] ``` ## Metodos de pago [#metodos-de-pago] ``` GET /api/v1/resources/available-payment-methods ``` `GET /api/v1/resources/available-payment-methods` Los medios que tu comercio tiene habilitados. Es lo que puedes listar en `advanced_options.payment_methods` al [generar un pago](/generate-transaction). :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "credit": ["Visa", "Mastercard"], "debit": [], "pse": ["pse"], "cash": ["Efecty", "Carulla"] } ``` ## Lista efectivos [#lista-efectivos] ``` GET /api/v1/resources/checkout/available-cash ``` `GET /api/v1/resources/checkout/available-cash` El valor que envías en `cash.franchise` al [cobrar en efectivo](/checkout-transaction#parametros-efectivos) es el **`name`**. `min` y `max` son los límites de monto de ese punto de recaudo. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "name": "Carulla", "logo": "/images/methods_payments/carulla.png", "association_code": 26212, "network": "Occidente", "active": true, "barcode": true, "min": 1, "max": 9999999 } ] ``` ## Lista bancos pse [#lista-bancos-pse] ``` GET /api/v1/resources/checkout/pse-banks ``` `GET /api/v1/resources/checkout/pse-banks` El valor que envías en `pse.financialInstitutionCode` es el **`financialInstitutionCode`**. :::caution La lista **cambia según el ambiente del token**. Consúltala siempre con el mismo token con el que vas a cobrar. ::: :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "financialInstitutionCode": "1022", "financialInstitutionName": "BANCO UNION COLOMBIANO" }, { "financialInstitutionCode": "1040", "financialInstitutionName": "BANCO AGRARIO" } ] ``` ## Tipos de identificación pse [#tipos-de-identificación-pse] ``` GET /api/v1/resources/checkout/pse-identification-types ``` `GET /api/v1/resources/checkout/pse-identification-types` `pse.userType` recibe el `value` del `user_type`, y `pse.identificationType` recibe uno de los `value` de **ese mismo** `user_type`. Mezclarlos hace fallar la validación. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "user_type": { "name": "Natural", "value": "person" }, "identification_types": [ { "name": "Cedula De Ciudadania", "value": "CedulaDeCiudadania" }, { "name": "Registro Civil De Nacimiento", "value": "RegistroCivilDeNacimiento" }, { "name": "Tarjeta De Identidad", "value": "TarjetaDeIdentidad" } ] }, { "user_type": { "name": "Juridica", "value": "company" }, "identification_types": [ { "name": "NIT", "value": "NIT" } ] } ] ``` ## Plantillas de checkout [#checkout-templates] ``` GET /api/v1/resources/get-checkout-templates ``` `GET /api/v1/resources/get-checkout-templates` Su `id` es lo que envías en `payment.checkout_template_id`. La plantilla decide qué campos se le piden al cliente, y por tanto **cuáles de los campos del checkout dejan de ser obligatorios**. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "id": 3, "name": "Checkout corto", "active": true, "offices": [] } ] ``` ## Estados de transacciones [#status-transaction] ``` GET /api/v1/resources/get-status-transaction ``` `GET /api/v1/resources/get-status-transaction` El campo `status` de una transacción trae el **`value`**, en español. :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json [ { "value": "Iniciada", "label": "Started", "index": 1 }, { "value": "Pendiente", "label": "Pending", "index": 2 }, { "value": "Aprobada", "label": "Approved", "index": 3 }, { "value": "Rechazada", "label": "Rejected", "index": 4 }, { "value": "Fallida", "label": "Failed", "index": 5 }, { "value": "Por Pagar", "label": "For Pay", "index": 6 }, { "value": "Reversada", "label": "Reversed", "index": 7 }, { "value": "Reversion Escalada", "label": "Escaleted Reversal", "index": 8 }, { "value": "Anulada", "label": "Cancelled", "index": 9 }, { "value": "Autorizada", "label": "Authorized", "index": 10 } ] ```