The Cannis API: your organization and your account

01 Before you start

Every request that arrives through the API goes into Cannis OS, under «Solicitudes de afiliación» (membership requests) of your organization, marked as coming from its website, and the organization gets an email notice. From there it is approved or rejected like any other.

• Access is requested. Cannis sets it up for your organization and hands you the token together with the final field names.
• The request is sent from your website's server. The form the person sees talks to your server, and your server talks to Cannis: the token never reaches the browser.
• The reCAPTCHA is solved in the form. The person solves it on your site and your server sends the result along with the request.

02 Base URL and format

Everything hangs from the /api prefix and answers JSON. It is a stateless API: no cookies, no session. Always send the Accept: application/json header: without it, some errors —such as too many requests— may come back as a web page instead of JSON.

Not every response of your organization's API has the same shape: the two lookups return an array and the submission returns an object with its status. Each section shows its own. Your account API lives under /api/v1 and always answers with the same envelope: ok, mensaje, datos and errores.

https://ns1.cannis.org/api

03 Authentication

Provinces and localities are open. The submission is not: it carries a token issued per organization, sent in the Authorization header. The token identifies the organization, so there is no need —and no way— to say which one it is: the request is tied to the token's organization.

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

• A token may or may not have an expiry date.
• A revoked token stops working instantly.
• Every use of the token is logged.
• The token is secret: it lives on your website's server, never in code that runs in the browser. Whoever has it can submit requests on behalf of your organization; if it leaked, ask for it to be revoked.

04 Provinces

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

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

05 Localities

[
  { "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://ns1.cannis.org/api/localidades?id_provincia=21"

06 Membership request

It submits the membership form an organization publishes on its own website: the person fills in their details there, your server sends them and the request enters Cannis OS, under «Solicitudes de afiliación» (membership requests) of your organization.

curl -X POST https://ns1.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 "cuit=27-30111222-4" \
  -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 Errors

Submission errors carry "status": "error". Validation errors come in messages, already written in Spanish with the readable field name: they can be shown as they are next to the form.

{
  "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."
  ]
}

If the reCAPTCHA does not verify, the 422 carries errors —an object with the field and its messages— instead of messages:

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

Without a token, or with one that does not work, the response is an object with status and message:

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

08 Your account API

It is the API the Cannis app uses, and it is open to any account: sign up, sign in, see and change one's own data, know which organizations the person operates and get into Cannis Pro. One single account, the same as on the website and in every product. The field names are the real ones.

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

Every response carries the same envelope. ok says whether it worked; mensaje is a text in Spanish that can be shown; datos is what was asked for and errores, on a 422, the messages per field.

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

Using this API requires an application key: it identifies the app, not the person, and Cannis issues it on request. It goes in the X-Cannis-App header of every request, including sign-up and sign-in; without it the response is 401. A key can be revoked on the spot, and every call is logged on our side.

Sign-up and sign-in return a token that identifies the person and the device. It travels in every request as Authorization: Bearer. It expires after 90 days without use and every use renews it; changing the password closes every other session. One token per device: dispositivo is the name the app gives it («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://ns1.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 Enter Cannis Pro

Cannis Pro is the cultivation module of Cannis. It uses the same account: a person who signs up on Cannis exists in Cannis Pro at once, with the same account number, and the other way round. What decides whether an organization can operate there is Cannis: it gives it a plan and, from that moment, its team gets in without another password. From the app, you get in with single-use access.

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