Solicitudes desde el sitio de tu organización

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 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.

https://asesores.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://asesores.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://asesores.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://asesores.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."
}