La API de Cannis: tu organización y tu cuenta

01 Antes de empezar

Cada solicitud que llega por la API entra a Cannis OS, en «Solicitudes de afiliación» de tu organización, marcada como llegada por su sitio, y la organización recibe un aviso por correo. Desde ahí se aprueba o se rechaza como cualquier otra.

• El acceso se pide. Cannis lo configura para tu organización y te entrega el token junto con los nombres definitivos de los campos.
• El alta se manda desde el servidor de tu sitio. El formulario que ve la persona le habla a tu servidor, y tu servidor a Cannis: el token nunca viaja al navegador.
• El reCAPTCHA se resuelve en el formulario. La persona lo resuelve en tu sitio y tu servidor manda el resultado junto con la solicitud.

02 Base y formato

Todo cuelga del prefijo /api y responde JSON. Es una API sin estado: no usa cookies ni sesión. Mandá siempre el encabezado Accept: application/json: sin él, algunos errores —como el de demasiados pedidos— pueden llegar como una página web en lugar de JSON.

Las respuestas de la API de tu organización no tienen todas la misma forma: las dos consultas devuelven un arreglo y el alta, un objeto con su status. Cada sección muestra la suya. La API de tu cuenta vive bajo /api/v1 y responde siempre el mismo sobre: ok, mensaje, datos y errores.

https://ns2.cannis.org/api

03 Autenticación

Provincias y localidades son abiertas. El alta no: va con un token que se emite por organización y viaja en el encabezado Authorization. El token identifica a la organización, así que no hace falta —ni se puede— mandar cuál es: la solicitud queda asociada a la del token.

Authorization: Bearer <tu-token>
Accept: application/json

• Un token puede tener fecha de vencimiento o no tenerla.
• Un token revocado deja de funcionar al instante.
• Queda registrado cada uso del token.
• El token es secreto: va en el servidor de tu sitio, nunca en el código que corre en el navegador. Quien lo tenga puede cargar solicitudes a nombre de tu organización; si se filtró, pedí que lo revoquen.

04 Provincias

[
  { "id_provincia": 1, "nombre": "Buenos Aires" },
  { "id_provincia": 2, "nombre": "Catamarca" }
]

curl -H "Accept: application/json" https://ns2.cannis.org/api/provincias

05 Localidades

[
  { "id": 1042, "nombre": "Rosario" },
  { "id": 1043, "nombre": "Venado Tuerto" }
]

{
  "message": "Parámetros inválidos",
  "errors": {
    "id_provincia": [ "El campo id provincia es obligatorio." ]
  }
}

curl -H "Accept: application/json" "https://ns2.cannis.org/api/localidades?id_provincia=21"

06 Solicitud de ingreso

Es el alta del formulario de ingreso que una organización publica en su propio sitio: la persona completa sus datos ahí, tu servidor los manda y la solicitud entra a Cannis OS, en «Solicitudes de afiliación» de tu organización.

curl -X POST https://ns2.cannis.org/api/post/solicitud_paciente \
  -H "Authorization: Bearer <tu-token>" \
  -H "Accept: application/json" \
  -F "nombre=Lucía" \
  -F "apellido=Fernández" \
  -F "documento=30111222" \
  -F "fecha_nacimiento=1983-04-12" \
  -F "[email protected]" \
  -F "celular=3415551234" \
  -F "provincia=21" \
  -F "localidad=1042" \
  -F "calle=San Martín" \
  -F "numero=1234" \
  -F "reprocann=1" \
  -F "consentimiento=1" \
  -F "captcha=<resultado-del-recaptcha>" \
  -F "[email protected]"

{
  "status": "success",
  "message": "Tu solicitud ha sido enviada exitosamente."
}

07 Errores

Los errores del alta traen "status": "error". Los de validación vienen en messages, ya redactados en español y con el nombre legible del campo: se pueden mostrar tal cual al lado del formulario.

{
  "status": "error",
  "messages": [
    "Email: Ya existe un registro con ese Email en esta ONG.",
    "Documento: El Documento debe contener entre 8 y 9 números."
  ]
}

Si el reCAPTCHA no verifica, el 422 trae errors —un objeto con el campo y sus mensajes— en lugar de messages:

{
  "status": "error",
  "errors": {
    "captcha": [ "Error en la verificación de reCAPTCHA." ]
  }
}

Sin token, o con uno que no sirve, la respuesta es un objeto con status y message:

{
  "status": "error",
  "message": "Token API no proporcionado."
}

08 La API de tu cuenta

Es la API que usa la app de Cannis, y está abierta a cualquier cuenta: registrarse, ingresar, ver y cambiar los datos propios, saber qué organizaciones opera la persona y entrar a Cannis Pro. Una cuenta sola, la misma del sitio y de todos los productos. Los nombres de los campos son los reales.

https://ns2.cannis.org/api/v1

Toda respuesta trae el mismo sobre. ok dice si salió; mensaje es un texto en español que se puede mostrar; datos es lo pedido y errores, en un 422, los mensajes por campo.

{ "ok": true,  "mensaje": "Listo.", "datos": { "…": "…" }, "errores": null }
{ "ok": false, "mensaje": "Qué pasó, en claro", "datos": null, "errores": { "campo": [ "mensaje" ] } }

Para usar esta API hace falta una clave de aplicación: identifica a la app, no a la persona, y Cannis la entrega a pedido. Va en el encabezado X-Cannis-App de cada pedido, incluidos el registro y el ingreso; sin ella la respuesta es 401. Una clave se puede revocar en el acto, y cada llamada queda registrada de nuestro lado.

El registro y el ingreso devuelven un token que identifica a la persona y al dispositivo. Viaja en cada pedido como Authorization: Bearer. Vence a los 90 días sin uso y cada uso lo renueva; cambiar la contraseña cierra todas las otras sesiones. Un token por dispositivo: dispositivo es el nombre que la app le pone («iPhone de Ana»).

X-Cannis-App: <clave-de-aplicación>
Authorization: Bearer <token-de-usuario>
Accept: application/json

{
  "ok": true, "mensaje": "Cuenta creada.",
  "datos": {
    "token": "12|Qx9…",
    "vence": "2027-01-29T14:05:00-03:00",
    "usuario": { "…": "los mismos datos de GET /api/v1/usuario" }
  },
  "errores": null
}

curl -X POST https://ns2.cannis.org/api/v1/ingresar \
  -H "X-Cannis-App: <clave-de-aplicación>" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…","dispositivo":"iPhone de Ana"}'

{
  "ok": true, "mensaje": "Listo.",
  "datos": { "usuario": {
    "id": 5120, "nombre": "Ana", "apellido": "Pérez", "apodo": "ana.perez",
    "email": "[email protected]", "email_verificado": true,
    "nacimiento": "1990-05-12", "celular": "5491155551234",
    "rol": { "codigo": "ONG", "etiqueta": "ONG" }, "avatar_url": null,
    "organizaciones": [
      { "origen": "ONG", "id": 12, "nombre": "Asociación Civil Raíces", "rol": "AD",
        "cannis_pro": { "habilitada": true, "plan": "gratis", "estado": "AC" } }
    ],
    "afiliaciones": [ { "ong_id": 30, "nombre": "Cultivo Sur", "estado": "AC", "desde": "2024-11-02" } ],
    "productos": { "cannis_os": true, "cannis_pro": true }
  } },
  "errores": null
}

09 Entrar a Cannis Pro

Cannis Pro es el módulo de cultivo de Cannis. Usa la misma cuenta: una persona que se registra en Cannis existe en Cannis Pro en el acto, con el mismo número de cuenta, y al revés. Lo que decide si una organización puede operar ahí es Cannis: le da un plan y, desde ese momento, su equipo entra sin otra contraseña. Desde la app se entra con un acceso de un solo uso.

{
  "ok": true, "mensaje": "Listo.",
  "datos": { "url": "https://app.cannis.pro/acceso-cannis?token=…", "vence_en": 120 },
  "errores": null
}