Documentación - API Broker

Manteca está organizada alrededor de la interfaz REST. Tiene URLs predecibles orientadas a recursos y usa códigos de respuesta HTTP estándar. Todos los valores de retorno son en formato JSON.

Contamos con un sandbox para que puedas probar el API sin alterar los flujos productivos. Para acceder al mismo, tendrás que usar la URL correspondiente (junto con sus API keys).

Por otro lado, para todo lo que es notificaciones hacia el lado del cliente, utilizamos webhooks. También contamos con un servicio de websockets para escuchar algunos eventos como los precios.

El API utiliza el protocolo HTTPS para exponenr los endpoints. No soporta HTTP.

Producción:

https://api.manteca.dev/broker

Sandbox:

https://sandbox.manteca.dev/broker

Manteca utiliza API keys para autenticar los requests. Las mismas son enviadas a través del header md-api-key

Las credenciales poseen privilegios completos por lo que es imprescindible que sean guardadas de manera segura. La interacción con Manteca debe ser siempre del lado del servidor, especialmente para los llamados autenticados.

En ciertas implementaciones donde lo creemos conveniente, también realizamos IP whitelisting para aumentar la seguridad.

API Broker usa respuestas HTTP estándar para indicar resultados exitosos o fallidos.

En general:

Códigos en el rango de 2xx indican éxito.
Códigos en el rango de 4xx indican un error relacionado a la información provista (como parámetros omitidos o con un tipo inválido).
Códigos en el rango de 5xx indican un error inesperado en Manteca.

Más allá de los códigos, en caso de error, se podrá acceder a más detalle a partir de visualizar el body de la respuesta. Siempre se maneja un mismo formato que contiene por un lado un internalStatus que hace referencia a un código verbal de error y por otro, un message que es básicamente una descripción algo más detallada del error.

Ejemplo de respuesta de error

internalStatusstring

Código verbal de error

messagestring

Descripción del error

200

Todo funcionó correctamente.

201

La creación de un recurso funcionó correctamente.

204

Todo funcionó correctamente y no hay response.

400

El request tiene algún error. Por lo general, son conflictos con los parámetros enviados.

401

Falta enviar el API key.

403

El API key no tiene suficientes permisos para realizar tal acción.

404

No existe el recurso referenciado.

409

La request genera un conflicto. Por ejemplo, por temas de duplicación de request.

429

La cantidad de requests enviados supera el límite impuesto.

500

Algo funcionó mal de nuestro lado.

Hay endpoints que devuelven arrays como response al pedido. En los casos en los que los datos pueden crecer dinámicamente, se devolverá la información de la paginación en el pedido y se aceptarán los siguientes parámetros para pedir los datos paginados.

Parámetros

page: Página actual, el default es 1.
limit: La cantidad de elementos por página, el default es 10.

Header Parameters

md-api-keystring

Query Parameters

pagestring

La página actual

limitstring

La cantidad de elementos en cada página

Podés configurar los webhook endpoints a través del API para ser notificado por cada uno de los eventos que ocurran y te sean de interés, esto te permite recibir información en tiempo real sobre las operaciones que son relevantes para tu sistema.

Entre ellos, encontrarás notificaciones relacionadas a cambios de estado de órdenes, sintéticos, depósitos y retiros.

Es importante destacar que para validar la autenticidad de tales mensajes, los firmamos mediante el uso de HMAC con el secreto compartido. Tal firma la podrán obtener del header md-webhook-signature.

Producción:

https://api.manteca.dev/broker

Sandbox:

https://sandbox.manteca.dev/broker

Existen dos tipos de compañía. PARTIALLY_MANAGED y FULLY_MANAGED.

FULLY_MANAGED

En este tipo la empresa no llevará un registro de los saldos de sus clientes ni de las operaciones bancarias, y no se permite deuda. El saldo final del usuario será 100% el saldo en Manteca. Las órdenes siempre utilizarán el saldo del cliente, sin generar deuda. Para ingresar saldos a la plataforma el cliente debe hacer un depósito y para retirar saldos el cliente debe hacer un retiro. Las ganancias se registran como un crédito especial que debe liquidarse por Manteca en un intervalo de tiempo específico acordado con la empresa

PARTIALLY_MANAGED

Este tipo está diseñado pensando en los Proveedores de Servicios de Pago (PSP). La empresa llevará un registro de al menos uno de los fiat (ARS, USD o ambos), y las operaciones se realizarán contra la deuda. La empresa gestiona el saldo de la moneda(s) asociadas. Manteca, por su parte, se encargará de gestionar el balance de la moneda no gestionada por la empresa, así como los activos de mercado asociados. Las órdenes contra la moneda manejada por la empresa siempre generarán deuda, sin utilizar el saldo del cliente. El resultado de la orden siempre aumentará el saldo del cliente, sin generar crédito. En caso de que sea la moneda manejada ésta se retira automáticamente apenas el mercado lo permita. Los depósitos de la moneda manejada siempre generarán crédito, sin aumentar el saldo del cliente. Se prohíben los retiros fiat de la moneda manejada y se realizan automáticamente al final del día, utilizando el saldo del cliente, sin generar deuda. Se permiten los retiros de las monedas no manejadas, utilizando el saldo del cliente, sin generar deuda. Las ganancias se registran como un crédito especial que debe liquidarse por Manteca en un intervalo de tiempo específico acordado con la empresa.

Se puede llegar a requerir una inversión inicial que consideramos reserva para proveer liquidez. La empresa tendrá un límite determinado en dólares que indicará cuánta deuda puede llegar a tener en el momento. Para aumentar el límite se puede otorgar más reservas de antemano. Cada cierto período se realizarán dos tipos de settlements. El primero, retiro de ganancias, donde Manteca enviará las ganancias a la compañía. El segundo, balancear la deuda contra el crédito de la empresa o Manteca y dejar registro del total operado durante ese ciclo. De ser necesario se harán transferencias entre la empresa y Manteca. La frecuencia de ambos settlements son independientes, pueden ocurrir en plazos determinados arbitrariamente.

Para altas de un cliente, Manteca asume que el email del cliente está verificado. El cliente se compone por dos módulos, la persona y el usuario.

Conflicto de Persona

Al dar de alta un cliente, la empresa otorgará los datos de la pesona del mismo. Si el individuo tuviese una persona registrada, se comparará los datos nuevos recibidos con los datos existentes. Si existe una diferencia entre los datos, se generará un conflicto. En este paso, se requiere intervención de un administrador de Manteca, el cual actualizará la persona con los datos más recientes.

Flujo de Onboarding

Empieza el alta con el endpoint de Onboarding inicial. Recibe email, legalId, personalData (datos personales simplificados, no todo. El resto se intentará obtener directamente de servicios de información como AFIP) e información de bancos. En la response, en caso de obtener la flag de causedConflict: True se debe esperar a que un administrador lo resuelva.

1

Registro

Se tiene que realizar el proceso de onboarding inicial con la informacion basica y obligatoria del usuario, utilizamos servicios como AFIP para obtener la información necesaria

2

Revisión

Se utiliza el chequeo de pendientes para revisar los datos que necesitan completar (que no lo pudimos obtener de AFIP) y los pasos a seguir para activar el usuario

3

Activación

Una vez subidas las imagenes de los DNIs, si son aprobados, realizamos registro del usuario ante servicios necesitarios para realizar las operaciones como ByMA

Para ejecutar cualquier tipo de operación en la plataforma, es obligatorio contar con un usuario registrado.

Para indetificarlos, se recomienda el uso del id y numberId que son los identificadores principales desde el lado de Manteca segun el endpoint.

Estados

EMAIL_VALIDATED ➜ requiere más información de la persona
PERSONAL_DATA_COMPLETE ➜ requiere información bancaria
USER_DATA_COMPLETE ➜ requiere subir DNIs
VALIDATING ➜ se subieron los DNIs correctamente y se están validando los datos, requiere esperar
VALIDATION_FAILED ➜ requiere resubir la documentación ya que fue rechazada
VALIDATED ➜ se validó la documentación subida, se inicia el registro contra servicios necesarios para la operatoria
ONBOARDING_FAILED ➜ requiere esperar a que un administrador de Manteca solucione el alta
ACTIVE ➜ el cliente está disponible para operar
BLOCKED ➜ el usuario fue bloqueado, contacte a soporte para obtener más detalles
INACTIVE ➜ la cuenta fue dada de baja

Para depositar balance en la cuenta de un cliente, el cliente debe hacer una transferencia bancaria con una cuenta bancaria a nombre del cliente (Mismo CUIT/CUIL).

Si un cliente tiene usuarios con dos compañías, se requiere intervención de un administrador de Manteca para que asigne el depósito a la compañía correspondiente.

Header Parameters

md-api-keystring

API Key otorgada por manteca.dev

Body Parameters

userIdstring Required

ID de un usuario

coinstring Required

Moneda del depósito

Enum values:

ARSUSD

amountnumber Required

Monto

{
  "id": "65bbdd03548400b379052d3b",
  "companyId": "658dd9502accccd05acc3ce9",
  "userId": "65bab11c23331f98515d2e50",
  "numberId": "10438",
  "legalId": "23999999995",
  "status": "ASSIGNED",
  "coin": "ARS",
  "amount": 100000,
  "creationTime": "2024-02-01T15:03:47.904-03:00",
  "updatedAt": "2024-02-01T15:03:47.904-03:00"
}

Header Parameters

md-api-keystring

API Key otorgada por manteca.dev

Query Parameters

pagestring

limitstring

bankIdstring

ID del banco

userIdstring

ID de un usuario

numberIdstring

ID numérico de un usuario

legalIdstring

CUIT/CUIL de un usuario

statusstring

Estado actual de un depósito

Enum values:

ASSIGNEDNOT_ASSIGNEDCANCELLED

coinstring

Moneda del depósito

Enum values:

ARSUSD

fromstring

Fecha en formato ISO8601

tostring

Fecha en formato ISO8601

{
  "totalCount": 1,
  "pageCount": 1,
  "pageSize": 10,
  "page": 1,
  "lastPage": 1,
  "data": [
    {
      "id": "65bbdd03548400b379052d3b",
      "companyId": "658dd9502accccd05acc3ce9",
      "userId": "65bab11c23331f98515d2e50",
      "numberId": "10438",
      "legalId": "23999999995",
      "status": "ASSIGNED",
      "coin": "ARS",
      "amount": 100000,
      "creationTime": "2024-02-01T15:03:47.904-03:00",
      "updatedAt": "2024-02-01T15:03:47.904-03:00"
    }
  ]
}

Header Parameters

md-api-keystring

API Key otorgada por manteca.dev

Path Parameters

depositIdstring Required

{
  "id": "65bbdd03548400b379052d3b",
  "companyId": "658dd9502accccd05acc3ce9",
  "userId": "65bab11c23331f98515d2e50",
  "numberId": "10438",
  "legalId": "23999999995",
  "status": "ASSIGNED",
  "coin": "ARS",
  "amount": 100000,
  "creationTime": "2024-02-01T15:03:47.904-03:00",
  "updatedAt": "2024-02-01T15:03:47.904-03:00"
}

Estados

PENDING ➜ Se inicia el proceso ante la entidad bancaria para enviar el dinero
PENDING_ADMIN ➜ La acción necesita una aprobación por parte de un administrador
PENDING_EXECUTION ➜ Se encuentra programado para ser procesado en el horario definido
PROCESSING ➜ Se encuentra en proceso en la entidad bancaria y estamos a la espera de una respuesta
FAILED ➜ Falló ante la entidad bancaria y necesita una revisión manual por parte de un administrador
RETRIED ➜ Se encontraba en estado fallido y un administrador creó uno nuevo para ser ejecutado a la brevedad
EXECUTED ➜ Se completó exitosamente el envío del dinero
CANCELLED ➜ Se canceló la operación por el usuario o por algún administrador

Estados

PENDING ➜ La órden fue creada, pero todavía no se envió a mercado
SENT ➜ La órden fue enviada a mercado
FAILED ➜ La órden llegó a mercado y fue rechazada
COMPLETED ➜ La órden se completó en su totalidad
CANCELLED ➜ La órden fue cancelada por el mercado o por algún administrador

Tiempos de acreditación

Una órden puede tener distintos tiempos de liquidación y, por tanto, de acreditación.

El resultado de la misma va a estar disponible una vez terminado dicho tiempo de acreditación.

CI ➜ Contado inmediato (T+0)
24hs ➜ Liquidación a un día (T+1)

Fees

Las comisiones que se cobran para una orden son:

platformFee ➜ Comisión que cobra Manteca por el uso de la plataforma
companyProfit ➜ Comisión que cobra la compañía cliente (ganancia)
marketRight ➜ Comisión que cobra el agente de bolsa por el acceso al mercado
iva ➜ Aplica para ciertos activos y tiene un valor constante de 21%
holdingIncomeFee ➜ Comisión que cobra el agente de bolsa a la ganancia generada por tenencia de activos
earningsWithholding ➜ Comisión que aplica solamente a préstamos o cauciones

Info

Diferencia entre amount y filledAmount

Una órden puede completarse parcialmente o en su totalidad.

amount ➜ cantidad enviada a mercado (lo que quiero operar)
filledAmount ➜ cantidad final operada (lo que se operó), puede ser igual o menor a amount

Un sintético es una automatización de múltiples órdenes de mercado, las etapas del sintético se ejecutan los días hábiles a partir de las 12:00hs.

Actualmente contamos con el siguiente tipo:

DOLAR_MEP ➜ Consiste en una compra de un activo del mercado seguido de una espera por regulaciones (para la compra). Luego se realiza una venta de ese activo del mercado contra la moneda fiat esperada. La compra del activo de mercado se hace con tiempo de acreditación instantánea y la venta del activo se hace con tiempo de acreditación de un día, a menos que la diferencia de precio contra instantáneo sea menor, en cuyo caso se ejecuta en modo instantáneo.

Estados

STARTING ➜ El sintético fue creado pero ninguna orden ha sido cursada
ACTIVE ➜ El sintético cuenta con una orden en el mercado
WAITING ➜ El sintético está esperando a terminar el tiempo de espera por regulaciones de mercado, se ejecutará la siguiente etapa cuando sea posible
PAUSED ➜ El sintético fue pausado manualmente y la siguiente etapa no se ejecutará, para ejecutarlo se debe usar el endpoint de “Ejecutar sintético”
FAILED ➜ El sintético tuvo algún error no recuperable en alguna etapa y requiere intervención manual
COMPLETED ➜ El sintético completó todas sus etapas exitosamente
CANCELLED ➜ El sintético fue manualmente cancelado

Para entender el funcionamiento del mercado de activos financieros, es crucial familiarizarse con ciertos términos que describen los precios y su comportamiento.

"ticker": "AL30 - CI" ➜ representa el símbolo o código del activo financiero
"buy": 76270 ➜ es el precio al que los compradores están dispuestos a adquirir el activo.
"sell": 76100 ➜ es el precio al que los vendedores están dispuestos a vender el activo.
"open": 77430 ➜ es el precio de apertura del activo en el mercado al inicio de la jornada.
"close": 76750 ➜ es el precio de cierre del activo al final de la jornada anterior.
"last": 76160 ➜ es el último precio al que se realizó una transacción del activo.
"high": 77430 ➜ es el precio más alto alcanzado por el activo durante la jornada.
"low": 75520 ➜ es el precio más bajo alcanzado por el activo durante la jornada.
"variation": { "daily": -0.00769} ➜ representa la variación del precio del activo.
"depth": {"buy": [{"size": 76,"price": 76200}],"sell": [{"size": 7203,"price": 76160}]} ➜ proporciona información sobre la profundidad del mercado.
"timestamp": 1739302729862 ➜ es una marca de tiempo que indica el momento en que se registraron estos datos.

Un dividendo es un pago que una empresa hace a sus accionistas, distribuyendo parte de sus ganancias, generalmente en efectivo o acciones.

Tipos

Existen diferentes tipos de dividendos dependiente el asset que lo genere.

DIVIDEND ➜ Son pagos que hacen las empresas a sus accionistas distribuyendo parte de sus ganancias ej. AAPL
BOND ➜ Son pago de intereces que hacen los gobiernos o empresas privadas por prestarle dinero ej. AL30 o MRCAO
MATURITY ➜ Expiracion de un asset ej. S31O4 o T2X5
REDEMPTION ➜ Son pagos de capital que hacen los gobiernos o empresas privadas por prestarle dinero ej. AL30 o MRCAO

Estados

Los dividendos pueden tener diferentes estados dependiendo la etapa de procesamiento en la cual se encuentra.

PENDING ➜ Creado, pero aún debe ser procesado
LOCKED_BY_FEES ➜ Procesado pero el usuario no tenía saldo suficiente para pagar las comisiones
PAID ➜ Procesado y pagado

Una empresa puede tener diferentes grupos de comisiones dependiendo el tipo de cliente, que se puede configurar al momento de crear el usuario.

Sections

Introducción

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Autenticación

Errores

Ejemplo de respuesta de error

Status Codes

Paginación

Parámetros

Header Parameters

Query Parameters

Webhooks

1

Configuración

2

Verificación HMAC

3

Procesamiento

Recursos principales

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Compañía

FULLY_MANAGED

PARTIALLY_MANAGED

Contabilidad

Onboarding

Usuario

Persona

Conflicto de Persona

Flujo de Onboarding

1

Registro

2

Revisión

3

Activación

Compliance

Usuarios

Estados

Balances

Bancos

Depósitos

1

Procesamiento

2

Análisis

3

Acreditación

Crear depósito

Header Parameters

Body Parameters

Response

Obtener depósitos

Header Parameters

Query Parameters

Response

Obtener depósito por ID

Header Parameters

Path Parameters

Response

Retiros

Estados

Órdenes

Estados

Tiempos de acreditación